Prometheus instrumentation library for Go applications
Go to file
Bjoern Rabenstein 84dc53148d Enable the Golang client library to create the new text formats.
Most important here is the simple & flat text format, but while I'm on
it, I have also added the text representations for protobufs (which is
purely meant for debugging purposes). I hope my basic idea about
handling those various protocols (and the text package) becomes
clearer now.

Change-Id: I7299853eadc82a426101e907f2b3d4e37f9e4c71
2014-04-25 21:45:04 +02:00
documentation Migrate documentation to markdown. 2013-04-28 19:21:30 +02:00
examples Enclose artifact generation process into Makefile. 2013-07-21 17:45:53 +02:00
extraction Eliminate a number of style-guide violations. 2014-04-25 21:18:04 +02:00
model Eliminate a number of style-guide violations. 2014-04-25 21:18:04 +02:00
prometheus Enable the Golang client library to create the new text formats. 2014-04-25 21:45:04 +02:00
test Remove the one duplication of the Tester interface. 2014-04-25 20:51:08 +02:00
text Enable the Golang client library to create the new text formats. 2014-04-25 21:45:04 +02:00
vendor/goautoneg Protocol Buffer negotiation support in handler. 2013-07-01 17:14:58 +02:00
.gitignore Enclose artifact generation process into Makefile. 2013-07-21 17:45:53 +02:00
.travis.yml Enclose artifact generation process into Makefile. 2013-07-21 17:45:53 +02:00
LICENSE Rearrange file and package per convention. 2013-04-04 15:27:09 +02:00
Makefile Optimize fingerprinting and metric locks. 2014-04-14 19:06:09 +02:00
README.md Eliminate a number of style-guide violations. 2014-04-25 21:18:04 +02:00
TODO Rearrange file and package per convention. 2013-04-04 15:27:09 +02:00

README.md

Overview

These Go 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

Build Status

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.

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

Testing

This package employs 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.

Contributing

Same as for the prometheus/prometheus repository, we are using Gerrit to manage reviews of pull-requests for this repository. See CONTRIBUTING.md in the prometheus/prometheus repository for details (but replace the prometheus repository name by client_golang).

Please try to avoid warnings flagged by go vet and by golint, and pay attention to the Go Code Review Comments.