README
¶
Overview
This Go package is an extraction of a piece of instrumentation code I whipped-up for a personal project that a friend of mine and I are working on. We were in need for some rudimentary statistics to observe behaviors of the server's various components, so this was written.
The code here is not a verbatim copy thereof but rather a thoughtful re-implementation should other folks need to consume and analyze such telemetry.
N.B. --- I have spent a bit of time working through the model in my head and probably haven't elucidated my ideas as clearly as I need to. If you examine examples/{simple,uniform_random}/main.go and registry.go, you'll find several examples of what types of potential instrumentation use cases this package addresses. There are probably numerous Go language idiomatic changes that need to be made, but this task has been deferred for now.
Continuous Integration
Documentation
Please read the generated documentation for the project's documentation from source code.
Basic Overview
Metrics
A metric is a measurement mechanism.
Gauge
A Gauge is a metric that exposes merely an instantaneous value or some snapshot thereof.
Histogram
A Histogram is a metric that captures events or samples into buckets. It exposes its values via percentile estimations.
Buckets
A Bucket is a generic container that collects samples and their values. It prescribes no behavior on its own aside from merely accepting a value, leaving it up to the concrete implementation to what to do with the injected values.
An Accumulating Bucket is a bucket that appends the new sample to a timestamped priority queue such that the eldest values are evicted according to a given policy.
Once an Accumulating Bucket reaches capacity, its eviction policy is invoked. This reaps the oldest N objects subject to certain behavior.
This merely removes the oldest N items without performing some aggregation replacement operation on them.
This removes the oldest N items while performing some summary aggregation operation thereupon, which is then appended to the list in the former values' place.
A Tallying Bucket differs from an Accumulating Bucket in that it never stores any of the values emitted into it but rather exposes a simplied summary representation thereof. For instance, if a values therein is requested, it may situationally emit a minimum, maximum, an average, or any other reduction mechanism requested.
Testing
This package employs gocheck for testing. Please ensure that all tests pass by running the following from the project root:
$ go test ./...
Documentation
¶
Overview ¶
registry.go provides a container for centralized exposition of metrics to their prospective consumers.
registry.Register("human_readable_metric_name", metric)
Please try to observe the following rules when naming metrics:
- Use underbars "_" to separate words.
- Have the metric name start from generality and work toward specificity toward the end. For example, when working with multiple caching subsystems, consider using the following structure "cache" + "user_credentials" → "cache_user_credentials" and "cache" + "value_transformations" → "cache_value_transformations".
- Have whatever is being measured follow the system and subsystem names cited supra. For instance, with "insertions", "deletions", "evictions", "replacements" of the above cache, they should be named as "cache_user_credentials_insertions" and "cache_user_credentials_deletions" and "cache_user_credentials_deletions" and "cache_user_credentials_evictions".
- If what is being measured has a standardized unit around it, consider providing a unit for it.
- Consider adding an additional suffix that designates what the value represents such as a "total" or "size"---e.g., "cache_user_credentials_size_kb" or "cache_user_credentials_insertions_total".
- Give heed to how future-proof the names are. Things may depend on these names; and as your service evolves, the calculated values may take on different meanings, which can be difficult to reflect if deployed code depends on antique names.
Further considerations:
- The Registry's exposition mechanism is not backed by authorization and authentication. This is something that will need to be addressed for production services that are directly exposed to the outside world.
- Engage in as little in-process processing of values as possible. The job of processing and aggregation of these values belongs in a separate post-processing job. The same goes for archiving. I will need to evaluate hooks into something like OpenTSBD.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultRegistry = NewRegistry()
This is the default registry with which Metric objects are associated. It is primarily a read-only object after server instantiation.
Functions ¶
Types ¶
type Registry ¶
type Registry struct {
NameToMetric map[string]metrics.Metric
// contains filtered or unexported fields
}
Registry is, as the name implies, a registrar where metrics are listed.
In most situations, using DefaultRegistry is sufficient versus creating one's own.
func NewRegistry ¶
func NewRegistry() *Registry
This builds a new metric registry. It is not needed in the majority of cases.
func (*Registry) YieldExporter ¶
func (registry *Registry) YieldExporter() http.HandlerFunc
Create a http.HandlerFunc that is tied to r Registry such that requests against it generate a representation of the housed metrics.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
random
main.go provides a simple example of how to use this instrumentation framework in the context of having something that emits values into its collectors.
|
main.go provides a simple example of how to use this instrumentation framework in the context of having something that emits values into its collectors. |
|
simple
main.go provides a simple skeletal example of how this instrumentation framework is registered and invoked.
|
main.go provides a simple skeletal example of how this instrumentation framework is registered and invoked. |
|
The maths package provides a number of mathematical-related helpers: distributions.go provides basic distribution-generating functions that are used primarily in testing contexts.
|
The maths package provides a number of mathematical-related helpers: distributions.go provides basic distribution-generating functions that are used primarily in testing contexts. |
|
bucket.go provides fundamental interface expectations for various bucket types.
|
bucket.go provides fundamental interface expectations for various bucket types. |