Prometheus 指标集成到 Java：simpleclient 库

Java 中的 Prometheus 指标：simpleclient 库完整指南

Prometheus 是一个强大的开源监控和告警系统，已成为云原生领域的事实标准。对于 Java 开发者来说，有多个库可用于集成，但官方库 simpleclient（也称为 prometheus/client_java）是最流行且维护最完善的。在本文中，我们将详细介绍如何使用该库将 Prometheus 指标添加到 Java 应用程序中。

什么是 simpleclient？

simpleclient 是 Prometheus 的官方 Java 客户端，提供了一种简单高效的方式来创建和导出指标。该库支持 Prometheus 的四种主要指标类型：

• Counter（计数器） — 单调递增的值（例如，请求数量）。
• Gauge（仪表盘） — 可以任意变化的值（例如，当前 CPU 负载）。
• Histogram（直方图） — 值在预定义“桶”中的分布（例如，响应时间）。
• Summary（摘要） — 观测值的分位数（例如，响应时间的 p50、p99）。

安装与配置

首先，将以下依赖项添加到您的 pom.xml（Maven）或 build.gradle（Gradle）中。

Maven

<dependency>    <groupId>io.prometheus</groupId>    <artifactId>simpleclient</artifactId>    <version>0.16.0</version></dependency>

<!-- 用于通过 HTTP 导出指标 --><dependency>    <groupId>io.prometheus</groupId>    <artifactId>simpleclient_httpserver</artifactId>    <version>0.16.0</version></dependency>

Gradle

implementation 'io.prometheus:simpleclient:0.16.0'implementation 'io.prometheus:simpleclient_httpserver:0.16.0'

创建和使用指标

我们来看一个在一个类中创建所有主要指标类型的示例。

import io.prometheus.client.Counter;import io.prometheus.client.Gauge;import io.prometheus.client.Histogram;import io.prometheus.client.Summary;

public class MetricsExample {

    // 1. Counter：已处理的请求数量    static final Counter requestsCounter = Counter.build()        .name("app_requests_total")        .help("Total number of processed requests.")        .labelNames("endpoint", "method")        .register();

    // 2. Gauge：当前活跃用户数    static final Gauge activeUsersGauge = Gauge.build()        .name("app_active_users")        .help("Current number of active users.")        .register();

    // 3. Histogram：请求执行时间（毫秒）    static final Histogram requestDurationHistogram = Histogram.build()        .name("app_request_duration_ms")        .help("Request duration in milliseconds.")        .buckets(10, 50, 100, 200, 500, 1000, 5000)        .register();

    // 4. Summary：执行时间分位数    static final Summary requestDurationSummary = Summary.build()        .name("app_request_duration_summary_ms")        .help("Request duration summary in milliseconds.")        .quantile(0.5, 0.05)   // p50，允许误差 5%        .quantile(0.99, 0.01)  // p99，允许误差 1%        .register();

    public static void main(String[] args) throws Exception {        // 模拟请求处理        for (int i = 0; i < 100; i++) {            processRequest("/api/users", "GET");        }

        // 启动 HTTP 服务器以导出指标        new HTTPServer(9090);        System.out.println("Metrics server started