prometheus-cpp

这是一个用于现代 C++ 的 Prometheus 客户端库。

这个库旨在为 C++ 服务启用基于指标的开发。它实现了 Prometheus 数据模型，这是一个强大的抽象概念，用于收集和展示指标。我们提供了通过 Prometheus 收集指标的可能性,但也可以添加其他推送/拉取收集方式作为插件。

使用

更详细的接口文档请参见 https://jupp0r.github.io/prometheus-cpp。

#include <prometheus/counter.h>
#include <prometheus/exposer.h>
#include <prometheus/registry.h>

#include <array>
#include <chrono>
#include <cstdlib>
#include <memory>
#include <string>
#include <thread>

int main() {
  using namespace prometheus;

  // 创建一个运行在 8080 端口的 HTTP 服务器
  Exposer exposer{"127.0.0.1:8080"};

  // 创建一个指标注册表
  // @注意: 保持对象存活是用户的责任
  auto registry = std::make_shared<Registry>();

  // 添加一个新的计数器族到注册表(族将具有相同名称但不同标签维度的值组合在一起)
  //
  // @注意: 请遵循指标命名最佳实践:
  // https://prometheus.io/docs/practices/naming/
  auto& packet_counter = BuildCounter()
                             .Name("observed_packets_total")
                             .Help("Number of observed packets")
                             .Register(*registry);

  // 添加并记住维度数据, 增加这些是非常廉价的
  auto& tcp_rx_counter =
      packet_counter.Add({{"protocol", "tcp"}, {"direction", "rx"}});
  auto& tcp_tx_counter =
      packet_counter.Add({{"protocol", "tcp"}, {"direction", "tx"}});
  auto& udp_rx_counter =
      packet_counter.Add({{"protocol", "udp"}, {"direction", "rx"}});
  auto& udp_tx_counter =
      packet_counter.Add({{"protocol", "udp"}, {"direction", "tx"}});

  // 添加一个在编译时不确定维度数据的计数器
  // 然而,维度值应该只出现在低基数中:
  // https://prometheus.io/docs/practices/naming/#labels
  auto& http_requests_counter = BuildCounter()
                                    .Name("http_requests_total")
                                    .Help("Number of HTTP requests")
                                    .Register(*registry);

  // 让暴露器在传入的 HTTP 请求中刮取注册表
  exposer.RegisterCollectable(registry);

  for (;;) {
    std::this_thread::sleep_for(std::chrono::seconds(1));
    const auto random_value = std::rand();

    if (random_value & 1) tcp_rx_counter.Increment();
    if (random_value & 2) tcp_tx_counter.Increment();
    if (random_value & 4) udp_rx_counter.Increment();
    if (random_value & 8) udp_tx_counter.Increment();

    const std::array<std::string, 4> methods = {"GET", "PUT", "POST", "HEAD"};
    auto method = methods.at(random_value % methods.size());
    // 动态调用 Family<T>.Add() 可以工作,但很慢,应该避免
    http_requests_counter.Add({{"method", method}}).Increment();
  }
  return 0;
}

要求

使用 prometheus-cpp 需要一个支持 C++11 的编译器。它已经在 Ubuntu Bionic (18.04) 上的 GNU GCC 7.4 和 Visual Studio 2017 上成功测试过。

构建

构建 prometheus-cpp 有两种支持的方式 - CMake 和 bazel。两种方式在 CI 中都经过测试,应该可以在 master 分支和所有发行版上工作。

如果这些说明对你来说不奏效,查看 GitHub Workflows 可能会有所帮助。

使用 CMake

对于 CMake 构建,请先获取子模块。请注意, zlib 和 libcurl 不是由包含的子模块提供的。在下面的示例中,它们的使用被禁用了。

然后按照惯例进行构建。

# 获取第三方依赖项
git submodule init
git submodule update

mkdir _build
cd _build

# 运行 cmake
cmake .. -DBUILD_SHARED_LIBS=ON -DENABLE_PUSH=OFF -DENABLE_COMPRESSION=OFF

# 构建
cmake --build . --parallel 4

# 运行测试
ctest -V

# 安装库和头文件
cmake --install .

使用 Bazel

安装一个支持模块的最新版本 bazel。 要构建和测试 prometheus-cpp,请运行:

bazel test //...

打包

通过配置 CPack,你可以生成一个安装程序,如 Debian 软件包 (.deb) 或 RPM (.rpm),用于静态或动态库,以便它们可以轻松地安装在其他系统上。 请参阅CPack文档,了解所有可用的生成器及其配置选项。

要生成Debian软件包,可以按照以下步骤操作:

# 获取第三方依赖项
git submodule update --init

# 运行cmake
cmake -B_build -DCPACK_GENERATOR=DEB -DBUILD_SHARED_LIBS=ON # 或 OFF以生成静态库

# 构建并打包
cmake --build _build --target package --parallel $(nproc)

这将在_build文件夹中生成一个命名恰当的.deb文件。要构建RPM软件包,请将CPACK_GENERATOR变量设置为RPM。

使用已安装的项目

CMake

通过CMake使用prometheus-cpp是首选方式,因为三个prometheus-cpp库之间的依赖关系都能得到正确处理。

cmake/project-import目录包含一个示例项目和最小的CMakeLists.txt文件。

Ubuntu PPA

Launchpad上的prometheus-cpp团队提供了一个用于稳定版本的PPA。请按照"将此PPA添加到您的系统"步骤进行使用。

vcpkg

vcpkg包管理器包含一个prometheus-cpp端口,已经在Linux、macOS和Windows上进行了测试。

Conan

Conan包管理器也包含prometheus-cpp软件包,位于ConanCenter存储库中。

Bazel

Bazel中心注册表(BCR)提供了prometheus-cpp软件包。在您的MODULE.bazel文件中添加以下内容:

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

纯Makefile

手动链接prometheus-cpp时,库的顺序很重要。所需的库取决于具体的使用情况,但以下内容应该适用于拉取指标的方法:

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

对于推送工作流,请尝试:

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

贡献

请遵守Google C++ 编码规范。在提交PR之前,请确保您的补丁符合clang-format格式要求。同时也要遵守这些提交信息指南。

您可以检出此存储库并使用以下命令构建库:

bazel build //...

使用以下命令运行单元测试:

bazel test //...

还有一个集成测试,使用telegraf来抓取示例服务器。安装telegraf后,可以使用以下命令运行该测试:

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

基准

这里有一个基准测试套件,您可以运行:

bazel run -c opt //core/benchmarks

信息：分析了目标//core/benchmarks:benchmarks（0个软件包加载，0个目标配置）。 发现1个目标... 目标//core/benchmarks:benchmarks最新: bazel-bin/core/benchmarks/benchmarks 耗时：0.356秒，关键路径：0.01秒，远程（耗时0.00%）：[排队：0.00%，设置：0.00%，处理：0.00%] 0个进程。 构建成功完成，共1个操作 构建成功完成，共1个操作 2018-11-30 15:13:14 在(4 X 2200 MHz CPU)上运行 CPU缓存： L1数据 32K (x2) L1指令 32K (x2) L2统一 262K (x2) L3统一 4194K (x1)

基准测试 时间 CPU 迭代

BM_Counter_Increment 13 纳秒 12 纳秒 55616469 BM_Counter_Collect 7 纳秒 7 纳秒 99823170 BM_Gauge_Increment 12 纳秒 12 纳秒 51511873 BM_Gauge_Decrement 12 纳秒 12 纳秒 56831098 BM_Gauge_SetToCurrentTime 184 纳秒 183 纳秒 3928964 BM_Gauge_Collect 6 纳秒 6 纳秒 117223478 BM_Histogram_Observe/0 134 纳秒 124 纳秒 5665310 BM_Histogram_Observe/1 122 纳秒 120 纳秒 5937185 BM_Histogram_Observe/8 137 纳秒 135 纳秒 4652863 BM_Histogram_Observe/64 143 纳秒 143 纳秒 4835957 BM_Histogram_Observe/512 259 纳秒 257 纳秒 2334750 BM_Histogram_Observe/4096 1545 纳秒 1393 纳秒 620754 BM_Histogram_Collect/0 103 纳秒 102 纳秒 5654829 BM_Histogram_Collect/1 100 纳秒 100 纳秒 7015153 BM_Histogram_Collect/8 608 纳秒 601 纳秒 1149652 BM_Histogram_Collect/64 1438 纳秒 1427 纳秒 515236 BM_Histogram_Collect/512 5178 纳秒 5159 纳秒 114619 BM_Histogram_Collect/4096 33527 纳秒 33280 纳秒 20785 BM_Registry_CreateFamily 320 纳秒 316 纳秒 2021567 BM_Registry_CreateCounter/0 128 纳秒 128 纳秒 5487140 BM_Registry_CreateCounter/1 2066 纳秒 2058 纳秒 386002 BM_Registry_CreateCounter/8 7672 纳秒 7634 纳秒 91328 BM_Registry_CreateCounter/64 63270 纳秒 62761 纳秒 10780 BM_Registry_CreateCounter/512 560714 纳秒 558328 纳秒 1176 BM_Registry_CreateCounter/4096 18672798 纳秒 18383000 纳秒 35 BM_Summary_Observe/0/iterations:262144 9351 纳秒 9305 纳秒 262144 BM_Summary_Observe/1/iterations:262144 9242 纳秒 9169 纳秒 262144 BM_Summary_Observe/8/iterations:262144 14344 纳秒 14195 纳秒 262144 BM_Summary_Observe/64/iterations:262144 19176 纳秒 18950 纳秒 262144 BM_Summary_Collect/0/0 31 纳秒 30 纳秒 24873766 BM_Summary_Collect/1/0 166 纳秒 166 纳秒 4266706 BM_Summary_Collect/8/0 1040 纳秒 1036 纳秒 660527 BM_Summary_Collect/64/0 4529 纳秒 4489 纳秒 155600 BM_Summary_Collect/0/1 28 纳秒 28 纳秒 24866697 BM_Summary_Collect/1/1 190 纳秒 188 纳秒 3930354 BM_Summary_Collect/8/1 1372 纳秒 1355 纳秒 535779 BM_Summary_Collect/64/1 9901 纳秒 9822 纳秒 64632 BM_Summary_Collect/0/8 29 纳秒 29 纳秒 24922651 BM_Summary_Collect/1/8 217 纳秒 215 纳秒 3278381 BM_Summary_Collect/8/8 2275 纳秒 2256 纳秒 282503 BM_Summary_Collect/64/8 56790 纳秒 55804 纳秒 13878 BM_Summary_Collect/0/64 32 纳秒 31 纳秒 22548350 BM_Summary_Collect/1/64 395 纳秒 389 纳秒 1817073 BM_Summary_Collect/8/64 10187 纳秒 10064 纳秒 71928 BM_Summary_Collect/64/64 374835 纳秒 373560 纳秒 1812 BM_Summary_Collect/0/512 28 纳秒 28 纳秒 25234228 BM_Summary_Collect/1/512 1710 纳秒 1639 纳秒 802285 BM_Summary_Collect/8/512 50355 纳秒 49335 纳秒 15975 BM_Summary_Collect/64/512 2520972 纳秒 2493417 纳秒 295 BM_Summary_Collect/0/4096 31 纳秒 31 纳秒 24059034 BM_Summary_Collect/1/4096 2719 纳秒 2698 纳秒 286186 BM_Summary_Collect/8/4096 121689 纳秒 119995 纳秒 5647 BM_Summary_Collect/64/4096 5660131 纳秒 5587634 纳秒 134 BM_Summary_Collect/0/32768 29 纳秒 29 纳秒 22217567 BM_Summary_Collect/1/32768 4344 纳秒 4294 纳秒 138135 BM_Summary_Collect/8/32768 331563 纳秒 326403 纳秒 2017 BM_Summary_Collect/64/32768 16363553 纳秒 16038182 纳秒 44 BM_Summary_Collect/0/262144 27 纳秒 27 纳秒 23923036 BM_Summary_Collect/1/262144 10457 纳秒 10332 纳秒 67690 BM_Summary_Collect/8/262144 930434 纳秒 869234 纳秒 792 BM_Summary_Collect/64/262144 39217069 纳秒 39054846 纳秒 13 BM_Summary_Observe_Common/iterations:262144 5587 纳秒 5557 纳秒 262144 BM_Summary_Collect_Common/0 676 纳秒 673 纳秒 1054630 BM_Summary_Collect_Common/1 709 纳秒 705 纳秒 990659 BM_Summary_Collect_Common/8 1030 纳秒 1025 纳秒 685649 BM_Summary_Collect_Common/64 2066 纳秒 2055 纳秒 339969 BM_Summary_Collect_Common/512 5754 纳秒 5248 纳秒 156895 BM_Summary_Collect_Common/4096 23894 纳秒 23292 纳秒 31096 BM_Summary_Collect_Common/32768 49831 纳秒 49292 纳秒 13492 BM_Summary_Collect_Common/262144 128723 纳秒 126987 纳秒 5579

项目状态

稳定和用于生产环境中。

库的某些部分由自身进行监控（收集的字节数、抓取次数、抓取请求延迟）。已有一个可工作的示例，被 telegraf 作为集成测试的一部分进行抓取。

常见问题解答

你支持哪些抓取格式？

仅支持 Prometheus 文本展示格式。对 protobuf 格式的支持已被移除，因为它在 Prometheus 2.0 中也被移除了。

许可证

MIT