83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# Overview
|
|
These [Go](http://golang.org) packages are an extraction of pieces 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
|
|
[](http://travis-ci.org/prometheus/client_golang)
|
|
|
|
# Documentation
|
|
Please read the [generated documentation](http://go.pkgdoc.org/github.com/prometheus/client_golang)
|
|
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.
|
|
|
|
### Counter
|
|
A _Counter_ is a metric that exposes merely a sum or tally of things.
|
|
|
|
### 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.
|
|
|
|
##### Accumulating Bucket
|
|
An _Accumulating Bucket_ is a _Bucket_ that appends the new sample to a queue
|
|
such that the eldest values are evicted according to a given policy.
|
|
|
|
###### Eviction Policies
|
|
Once an _Accumulating Bucket_ reaches capacity, its eviction policy is invoked.
|
|
This reaps the oldest N objects subject to certain behavior.
|
|
|
|
####### Remove Oldest
|
|
This merely removes the oldest N items without performing some aggregation
|
|
replacement operation on them.
|
|
|
|
####### Aggregate Oldest
|
|
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.
|
|
|
|
##### Tallying Bucket
|
|
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.
|
|
|
|
# Getting Started
|
|
|
|
* The source code is periodically indexed: [Go Exposition Client](http://godoc.org/github.com/prometheus/client_golang).
|
|
* All of the core developers are accessible via the [Prometheus Developers Mailinglist](https://groups.google.com/forum/?fromgroups#!forum/prometheus-developers).
|
|
|
|
|
|
# Testing
|
|
This package employs [gocheck](http://labix.org/gocheck) for testing. Please
|
|
ensure that all tests pass by running the following from the project root:
|
|
|
|
$ go test ./...
|
|
|
|
The use of gocheck is summarily being phased out; however, old tests that use it
|
|
still exist.
|