Java 后端 / 系统课时

采集 Micrometer 指标

采集 Micrometer 指标

Micrometer 把业务代码中的计数、耗时和当前状态转换为统一指标。本课将接入指标注册表,编写 Counter、Timer、Gauge 主示例,并通过 Actuator 与 Prometheus 格式验证采集结果。

学习目标

  • 根据业务语义选择 Counter、Timer 和 Gauge。
  • 使用 MeterRegistry 注册低基数、可聚合的自定义指标。
  • 通过 /actuator/metrics 和 /actuator/prometheus 验证指标。

选择正确的指标类型

Micrometer 的核心是 MeterRegistry。业务代码向注册表记录数据,Actuator 可以用于诊断查询,监控注册表则把同一批指标转换为 Prometheus 等后端需要的格式。

类型 记录内容 典型场景
Counter 只增不减的累计次数 创建订单数、失败次数
Timer 调用次数与耗时分布 接口处理时间、外部调用延迟
Gauge 某一时刻的当前值 队列长度、处理中任务数

Timer 已经包含调用次数,不要只为统计同一事件次数再复制一个 Counter。Gauge 适合会增会减的状态值,而且被观测对象必须保持有效引用。标签应使用渠道、结果、区域等有限集合,禁止把订单号、用户 ID 或请求路径原文作为标签。

Micrometer 指标从业务代码到监控系统的数据流

接入注册表并编写指标

独立运行本示例需要 Actuator 与 Prometheus 注册表。Spring Boot 会自动创建 MeterRegistry,并把 JVM、HTTP、线程池等内置指标一并注册。

xml
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

开放诊断和抓取端点,并给所有指标增加稳定的应用标签。直方图会增加时间序列数量,只应为确实需要分位数或延迟分布的 Timer 开启。

yaml
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  metrics:
    tags:
      application: order-service
    distribution:
      percentiles-histogram:
        orders.processing: true

将下面代码保存为 MetricsDemoApplication.java。一次创建请求会增加订单计数,用 Timer 记录处理耗时,并在处理期间调整待处理订单 Gauge。

java
package com.example.metrics;

import java.time.Duration;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.locks.LockSupport;

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class MetricsDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(MetricsDemoApplication.class, args);
    }
}

@RestController
class OrderController {

    private final OrderMetrics metrics;

    OrderController(OrderMetrics metrics) {
        this.metrics = metrics;
    }

    @PostMapping("/orders")
    Map<String, String> createOrder() {
        return Map.of("status", metrics.recordCreation());
    }
}

@Component
class OrderMetrics {

    private final Counter createdCounter;
    private final Timer processingTimer;
    private final AtomicInteger pendingOrders = new AtomicInteger();

    OrderMetrics(MeterRegistry registry) {
        this.createdCounter = Counter.builder("orders.created")
                .description("Accepted order count")
                .tag("channel", "api")
                .register(registry);

        this.processingTimer = Timer.builder("orders.processing")
                .description("Order processing latency")
                .publishPercentileHistogram()
                .register(registry);

        Gauge.builder("orders.pending", pendingOrders, AtomicInteger::get)
                .description("Orders currently being processed")
                .register(registry);
    }

    String recordCreation() {
        pendingOrders.incrementAndGet();
        try {
            return processingTimer.record(() -> {
                // 模拟业务耗时;真实项目中替换为订单保存与事件发布。
                LockSupport.parkNanos(Duration.ofMillis(80).toNanos());
                createdCounter.increment();
                return "accepted";
            });
        } finally {
            pendingOrders.decrementAndGet();
        }
    }
}

预期输出

text
Started MetricsDemoApplication in <TIME> seconds

<TIME> 由机器性能决定。应用启动后,Spring 会自动把三个自定义 Meter 注册到同一个注册表。

调用接口并验证采集结果

先创建一个订单,再查询 Counter 与 Gauge。指标值取决于调用次数和查询时刻,因此使用动态占位符表示;首次调用后 <COUNT> 通常为 1.0,请求结束后 <CURRENT_PENDING> 通常为 0.0。

bash
curl -s -X POST http://localhost:8080/orders
curl -s "http://localhost:8080/actuator/metrics/orders.created?tag=channel:api"
curl -s http://localhost:8080/actuator/metrics/orders.pending

预期输出

text
{"status":"accepted"}
{"name":"orders.created","measurements":[{"statistic":"COUNT","value":<COUNT>}],...}
{"name":"orders.pending","measurements":[{"statistic":"VALUE","value":<CURRENT_PENDING>}],...}

再检查 Prometheus 暴露格式。标签顺序和浮点值可能不同,但应能找到计数、Timer 调用次数和当前待处理数。

bash
curl -s http://localhost:8080/actuator/prometheus | grep -E '^orders_(created_total|processing_seconds_count|pending)'

预期输出

text
orders_created_total{application="order-service",channel="api"} <COUNT>
orders_processing_seconds_count{application="order-service"} <COUNT>
orders_pending{application="order-service"} <CURRENT_PENDING>

若 /actuator/metrics 找不到名称,先确认代码路径至少执行过一次;若 /actuator/prometheus 为 404,检查 Prometheus 注册表依赖和端点暴露白名单。出现大量时间序列时,应优先检查标签中是否混入了高基数值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

采集 Micrometer 指标

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通