Prometheus instrumentation library for Go applications
Go to file
beorn7 1b2bd1d665 Make Histogram observations atomic while keeping them lock-free
Fixes #275

This is rather tricky and required some studying of the Go memory
model. I have added copious code comments to explain what's going on.

Benchmarks haven't changed significantly, despite the additional
atomic operations now required during Observe. Write performance is
noticable, but it is also much more involved now and has a mutex. (But
note that Write is supposed to be a relatively rare operation and thus
not in the hot path compared to Observe.) Allocs haven't changed at
all.

OLD:

BenchmarkHistogramWithLabelValues-4     10000000               151 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramNoLabels-4            50000000                36.0 ns/op             0 B/op          0 allocs/op
BenchmarkHistogramObserve1-4            50000000                28.1 ns/op             0 B/op          0 allocs/op
BenchmarkHistogramObserve2-4            10000000               160 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramObserve4-4             5000000               378 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramObserve8-4             2000000               768 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramWrite1-4               1000000              1589 ns/op             896 B/op         37 allocs/op
BenchmarkHistogramWrite2-4                500000              2973 ns/op            1792 B/op         74 allocs/op
BenchmarkHistogramWrite4-4                300000              6979 ns/op            3584 B/op        148 allocs/op
BenchmarkHistogramWrite8-4                100000             10701 ns/op            7168 B/op        296 allocs/op

NEW:

BenchmarkHistogramWithLabelValues-4     10000000               191 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramNoLabels-4            30000000                50.1 ns/op             0 B/op          0 allocs/op
BenchmarkHistogramObserve1-4            30000000                40.0 ns/op             0 B/op          0 allocs/op
BenchmarkHistogramObserve2-4            20000000                91.5 ns/op             0 B/op          0 allocs/op
BenchmarkHistogramObserve4-4             5000000               317 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramObserve8-4             2000000               636 ns/op               0 B/op          0 allocs/op
BenchmarkHistogramWrite1-4               1000000              2072 ns/op             896 B/op         37 allocs/op
BenchmarkHistogramWrite2-4                300000              3729 ns/op            1792 B/op         74 allocs/op
BenchmarkHistogramWrite4-4                200000              7847 ns/op            3584 B/op        148 allocs/op
BenchmarkHistogramWrite8-4                100000             16975 ns/op            7168 B/op        296 allocs/op

Signed-off-by: beorn7 <beorn@soundcloud.com>
2018-09-12 15:03:44 +02:00
api Update DefaultRoundTripper to DialContext because Dial is deprecated 2018-06-27 12:02:52 +02:00
examples Move both examples into single Dockerfile for Docker Hub (fixes #347) 2018-07-09 19:09:06 +01:00
prometheus Make Histogram observations atomic while keeping them lock-free 2018-09-12 15:03:44 +02:00
.gitignore Create Docker images for the examples 2017-09-19 13:59:05 +01:00
.travis.yml Add test-short target and use it in CI 2018-08-28 15:13:08 +02:00
CHANGELOG.md Cut v0.8.0 2016-08-17 16:08:12 +02:00
CONTRIBUTING.md Mention the DCO in the contributing guide 2018-05-31 14:22:30 +00:00
Dockerfile Using the recommended label syntax for maintainer in Dockerfile. 2018-08-27 08:28:47 -07:00
ISSUE_TEMPLATE.md Add an issue template 2018-02-09 13:47:34 +01:00
LICENSE License cleanup 2015-01-22 16:13:15 +01:00
MAINTAINERS.md Make Krasi the maintainer for the HTTP API client 2018-06-06 13:14:29 +02:00
Makefile Add test-short target and use it in CI 2018-08-28 15:13:08 +02:00
Makefile.common Add prometheus common makefile (#446) 2018-08-24 12:10:16 +02:00
NOTICE Create a public registry interface and separate out HTTP exposition 2016-08-02 18:46:22 +02:00
README.md Add Godoc link at the top of the README 2018-02-15 11:45:41 +00:00
VERSION Cut v0.8.0 2016-08-17 16:08:12 +02:00

README.md

Prometheus Go client library

Build Status Go Report Card go-doc

This is the Go client library for Prometheus. It has two separate parts, one for instrumenting application code, and one for creating clients that talk to the Prometheus HTTP API.

This library requires Go1.7 or later.

Important note about releases, versioning, tagging, stability, and your favorite Go dependency management tool

While our goal is to follow Semantic Versioning, this repository is still pre-1.0.0. To quote the Semantic Versioning spec: “Anything may change at any time. The public API should not be considered stable.” We know that this is at odds with the widespread use of this library. However, just declaring something 1.0.0 doesn't make it 1.0.0. Instead, we are working towards a 1.0.0 release that actually deserves its major version number.

Having said that, we aim for always keeping the tip of master in a workable state and for only introducing ”mildly” breaking changes up to and including v0.9.0. After that, a number of ”hard” breaking changes are planned, see the v0.10.0 milestone, which should get the library much closer to 1.0.0 state.

Dependency management in Go projects is still in flux, and there are many tools floating around. While dep might develop into the de-facto standard tool, it is still officially experimental. The roadmap for this library has been laid out with a lot of sometimes painful experience in mind. We really cannot adjust it every other month to the needs of the currently most popular or most promising Go dependency management tool. The recommended course of action with dependency management tools is the following:

  • Do not expect strict post-1.0.0 semver semantics prior to the 1.0.0 release. If your dependency management tool expects strict post-1.0.0 semver semantics, you have to wait. Sorry.
  • If you want absolute certainty, please lock to a specific commit. You can also lock to tags, but please don't ask for more tagging. This would suggest some release or stability testing procedure that simply is not in place. As said above, we are aiming for stability of the tip of master, but if we tagged every single commit, locking to tags would be the same as locking to commits.
  • If you want to get the newer features and improvements and are willing to take the minor risk of newly introduced bugs and “mild” breakage, just always update to the tip of master (which is essentially the original idea of Go dependency management). We recommend to not use features marked as deprecated in this case.
  • Once v0.9.0 is out, you could lock to v0.9.x to get bugfixes (and perhaps minor new features) while avoiding the “hard” breakage that will come with post-0.9 features.

Instrumenting applications

code-coverage go-doc

The prometheus directory contains the instrumentation library. See the best practices section of the Prometheus documentation to learn more about instrumenting applications.

The examples directory contains simple examples of instrumented code.

Client for the Prometheus HTTP API

code-coverage go-doc

The api/prometheus directory contains the client for the Prometheus HTTP API. It allows you to write Go applications that query time series data from a Prometheus server. It is still in alpha stage.

Where is model, extraction, and text?

The model packages has been moved to prometheus/common/model.

The extraction and text packages are now contained in prometheus/common/expfmt.

Contributing and community

See the contributing guidelines and the Community section of the homepage.