prometheus-cpp

Prometheus Client Library for Modern C++

This library aims to enable Metrics-Driven Development for C++ services. It implements the Prometheus Data Model, a powerful abstraction on which to collect and expose metrics. We offer the possibility for metrics to be collected by Prometheus, but other push/pull collections can be added as plugins.

Usage

See https://jupp0r.github.io/prometheus-cpp for more detailed interface documentation.

…

Requirements

Using prometheus-cpp requires a C++17 compliant compiler.

Building

There are two supported ways to build prometheus-cpp - CMake and bazel. Both are tested in CI and should work on master and for all releases.

In case these instructions don't work for you, looking at the GitHub Workflows might help.

With CMake

prometheus-cpp does not vendor its dependencies. It expects the following libraries to already be installed and discoverable via find_package():

• civetweb
• googletest (optional, needed for ENABLE_TESTING)
• benchmark (optional, needed for benchmarks)
• zlib (optional, needed for ENABLE_COMPRESSION)
• libcurl (optional, needed for ENABLE_PUSH)

Use whichever package manager you prefer to provide them, e.g. vcpkg, Conan, your system's package manager, or a manually installed copy. In the example below push support and compression are disabled to keep the dependency list minimal.

mkdir _build
cd _build

# run cmake
cmake .. -DBUILD_SHARED_LIBS=ON -DENABLE_PUSH=OFF -DENABLE_COMPRESSION=OFF

# build
cmake --build . --parallel 4

# run tests
ctest -V

# install the libraries and headers
cmake --install .

With Bazel

Install a recent bazel version with Modules support. To build and test prometheus-cpp run:

bazel test //...

Packaging

By configuring CPack you can generate an installer like a Debian package (.deb) or RPM (.rpm) for the static or dynamic libraries so they can be easily installed on other systems.

Please refer to the CPack documentation for all available generators and their configuration options.

To generate a Debian package you could follow these steps:

# run cmake
cmake -B_build -DCPACK_GENERATOR=DEB -DBUILD_SHARED_LIBS=ON # or OFF for static libraries

# build and package
cmake --build _build --target package --parallel $(nproc)

This will place an appropriately named .deb in the _build folder. To build a RPM package set the CPACK_GENERATOR variable to RPM.

Consuming the installed project

CMake

Consuming prometheus-cpp via CMake is the preferred way because all the dependencies between the three prometheus-cpp libraries are handled correctly.

The cmake/project-import directory contains an example project and minimal CMakeLists.txt.

Ubuntu PPA

The Launchpad prometheus-cpp team provides a PPA for stable versions. Please follow the "Adding this PPA to your system" steps to use it.

vcpkg

The vcpkg package manager contains a prometheus-cpp port which has been tested on Linux, macOS, and Windows.

Conan

Conan package manager contains prometheus-cpp package as well in ConanCenter repository

Bazel

The Bazel Central Registry (BCR provides the prometheus-cpp package. Add the following to your MODULE.bazel file:

bazel_dep(name = "prometheus-cpp", version = "1.2.4")

Plain Makefiles

When manually linking prometheus-cpp the library order matters. The needed libraries depend on the individual use case but the following should work for the pull metrics approach:

-lprometheus-cpp-pull -lprometheus-cpp-core -lz

For the push-workflow please try:

-lprometheus-cpp-push -lprometheus-cpp-core -lcurl -lz

Contributing

Please adhere to the Google C++ Style Guide. Make sure to clang-format your patches before opening a PR. Also make sure to adhere to these commit message guidelines.

You can check out this repo and build the library using

bazel build //...

Run the unit tests using

bazel test //...

There is also an integration test that uses telegraf to scrape a sample server. With telegraf installed, it can be run using

bazel test //pull/tests/integration:scrape-test

Benchmarks

There's a benchmark suite you can run:

…

Project Status

Stable and used in production.

Parts of the library are instrumented by itself (bytes scraped, number of scrapes, scrape request latencies). There is a working example that's scraped by telegraf as part of integration tests.

FAQ

What scrape formats do you support

Only the Prometheus Text Exposition Format. Support for the protobuf format was removed because it's been removed from Prometheus 2.0.

License

MIT