Prometheus instrumentation library for Go applications
Go to file
Björn Rabenstein 26e258bb9c
Merge pull request #527 from prometheus/mdl-no-cursing
prometheus: reword comment to avoid cursing
2019-01-17 00:08:44 +01:00
.github Release v0.9.0 2018-10-15 13:28:28 +02:00
api Add support for fetching rules with API client (#508) 2019-01-16 00:34:51 +03:00
examples Move both examples into single Dockerfile for Docker Hub (fixes #347) 2018-07-09 19:09:06 +01:00
prometheus prometheus: reword comment to avoid cursing 2019-01-16 17:03:06 -05:00
.gitignore Create Docker images for the examples 2017-09-19 13:59:05 +01:00
.travis.yml Add Go 1.11. 2018-09-19 12:24:24 +02:00
CHANGELOG.md Cut v0.9.2 2018-12-06 22:25:53 +01: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
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 Handle items newly deprecated in Go 1.11 2018-09-19 13:30:14 +02:00
Makefile.common Update Makefile.common to current upstream version 2019-01-05 21:56:06 +01:00
NOTICE Create a public registry interface and separate out HTTP exposition 2016-08-02 18:46:22 +02:00
README.md Release v0.9.0 2018-10-15 13:28:28 +02:00
VERSION Cut v0.9.2 2018-12-06 22:25:53 +01:00
go.mod Update vendoring 2018-12-18 17:11:19 +01:00
go.sum Update vendoring 2018-12-18 17:11:19 +01: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, and stability

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. We occasionally tag versions and track their changes in CHANGELOG.md, but this happens mostly to keep dependency management tools happy and to give people a handle they can talk about easily. In particular, all commits in the master branch have passed the same testing and reviewing. There is no QA process in place that would render tagged commits more stable or better tested than others.

There is a plan behind the current (pre-1.0.0) versioning, though:

  • v0.9 is the “production release”, currently tracked in the master branch. “Patch” releases will usually be just bug fixes, indeed, but important new features that do not require invasive code changes might also be included in those. We do not plan any breaking changes from one v0.9.x release to any later v0.9.y release, but nothing is guaranteed. Since the master branch will eventually be switched over to track the upcoming v0.10 (see below), we recommend to tell your dependency management tool of choice to use the latest v0.9.x release, at least for your production software. In that way, you should get bug fixes and non-invasive, low-risk new features without the need to change anything on your part.
  • v0.10 is a planned release that will have a lot of breaking changes (despite being only a “minor” release in the Semantic Versioning terminology, but as said, pre-1.0.0 means nothing is guaranteed). Essentially, we have been piling up feature requests that require breaking changes for a while, and they are all collected in the v0.10 milestone. Since there will be so many breaking changes, the development for v0.10 is currently not happening in the master branch, but in the dev-0.10 branch. It will violently change for a while, and it will definitely be in a non-working state now and then. It should only be used for sneak-peaks and discussions of the new features and designs.
  • Once v0.10 is ready for real-life use, it will be merged into the master branch (which is the reason why you should lock your dependency management tool to v0.9.x and only migrate to v0.10 when both you and v0.10 are ready for it). In the ideal case, v0.10 will be the basis for the future v1.0 release, but we cannot provide an ETA at this time.

Instrumenting applications

code-coverage go-doc

The prometheus directory contains the instrumentation library. See the guide on the Prometheus website 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.