Spring Boot 应用 Metrics 埋点实践记录（2026）

// 这里要注入 Spring 管理的 RestClient.Builder，才能获得自动埋点
// Spring Boot 自动配置会在 RestClient.Builder 上挂载 ObservationInterceptor
@Configuration
public class HttpClientConfig {

    @Bean
    public RestClient userServiceClient(RestClient.Builder builder) {
        return builder
            .baseUrl("http://user-service")
            .build();
    }
}

// user-service/build.gradle.kts
implementation("net.ttddyy.observation:datasource-micrometer-spring-boot:1.0.6")

spring:
  kafka:
    template:
      observation-enabled: true    # KafkaTemplate 生产者 metrics
    listener:
      observation-enabled: true    # @KafkaListener 消费者 metrics

spring:
  threads:
    virtual:
      enabled: true

management:
  observations:
    annotations:
      enabled: true

<!-- pom.xml 或 build.gradle：AOP 支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

@Service
public class HelloService {

    @Observed(
        name = "hello.service.getHello",     // Metric 名称（低基数，用于聚合）
        contextualName = "getHello"           // Span 名称（出现在链路追踪中）
    )
    public HelloResponse getHello(Long userId, String acceptLanguage) {
        // 业务逻辑
    }
}

@Observed(
    name = "greeting.resolve",
    contextualName = "resolveGreeting",
    lowCardinalityKeyValues = {"cache", "redis"}   // 固定值 key-value，适合做 Label
)
public Greeting getGreeting(String language) {
    // ...
}

@Observed(name = "hello.service.getHello", contextualName = "getHello")
public HelloResponse getHello(Long userId, String acceptLanguage) {

    // ✅ 高基数字段 → 放到 Span Attribute（只在追踪系统中，不进 Metrics）
    var current = registry.getCurrentObservation();
    if (current != null) {
        current.highCardinalityKeyValue("user.id", userId.toString());
    }

    // ❌ 不要这样做：高基数值作为 Metric 维度
    // current.lowCardinalityKeyValue("user.id", userId.toString());
}

@Service
public class GreetingService {

    private final ObservationRegistry registry;
    private final StringRedisTemplate redis;

    public GreetingService(ObservationRegistry registry, StringRedisTemplate redis) {
        this.registry = registry;
        this.redis = redis;
    }

    // @Observed 覆盖整个方法，自动处理正常路径
    @Observed(
        name = "greeting.resolve",
        contextualName = "resolveGreeting",
        lowCardinalityKeyValues = {"cache", "redis"}
    )
    public Greeting getGreeting(String language) {
        String cacheKey = "greeting:" + language;

        // 缓存命中：Lettuce 自动生成 db.redis span
        String cachedMessage = redis.opsForValue().get(cacheKey);
        if (cachedMessage != null) {
            return new Greeting(language, cachedMessage);
        }

        // 缓存未命中：手动 Observation 单独记录这段逻辑的耗时
        return resolveFromSource(language, cacheKey);
    }

    private Greeting resolveFromSource(String language, String cacheKey) {
        // ✅ 推荐：.observe() 函数式 API，自动处理 start/stop/error/scope
        return Observation.createNotStarted("greeting.lookup", registry)
            .lowCardinalityKeyValue("language", language)
            .observe(() -> {
                Greeting greeting = GREETINGS.getOrDefault(language, GREETINGS.get("en"));
                redis.opsForValue().set(cacheKey, greeting.message(), CACHE_TTL);
                return greeting;
            });
    }
}

// 手动模式：需要在运行时动态附加维度时使用
private Greeting resolveFromSource(String language, String cacheKey) {
    Observation lookup = Observation.createNotStarted("greeting.lookup", registry)
        .lowCardinalityKeyValue("language", language)
        .start();

    try (Observation.Scope scope = lookup.openScope()) {
        Greeting greeting = GREETINGS.getOrDefault(language, GREETINGS.get("en"));
        // 运行时才能确定的维度
        lookup.lowCardinalityKeyValue("source", greeting.source());
        redis.opsForValue().set(cacheKey, greeting.message(), CACHE_TTL);
        return greeting;
    } catch (Exception e) {
        lookup.error(e);
        throw e;
    } finally {
        lookup.stop();   // finally 确保无论异常与否都记录耗时
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    private final ObservationRegistry registry;

    public GlobalExceptionHandler(ObservationRegistry registry) {
        this.registry = registry;
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ProblemDetail> handleException(Exception ex) {
        // ✅ 通过 Micrometer 抽象层记录异常，后端无关
        Observation observation = registry.getCurrentObservation();
        if (observation != null) {
            observation.error(ex);  // 自动写入 Span exception 事件 + 标记 ERROR 状态
                                    // + 在 Metrics 中增加 error tag，Prometheus 可聚合
        }

        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
        problem.setDetail(ex.getMessage());
        return ResponseEntity.status(500).body(problem);
    }
}

management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus  # 按需暴露
  metrics:
    distribution:
      percentiles-histogram:
        http.server.requests: true    # 开启直方图，支持 Prometheus histogram_quantile()
      percentiles:
        http.server.requests: 0.5, 0.95, 0.99   # 或使用固定分位数（不支持自定义 range）

management:
  otlp:
    metrics:
      export:
        url: http://localhost:4318/v1/metrics
        step: 10s    # 推送间隔，生产环境建议 30s～60s，减少带宽压力

management:
  observations:
    annotations:
      enabled: true    # Spring Boot 3.5 需显式开启，否则 @Observed 静默无效

# application-prod.yaml
management:
  endpoints:
    web:
      exposure:
        include: health, prometheus    # 生产只暴露健康检查和 metrics 端点
  endpoint:
    health:
      show-details: never             # 不对外暴露详细健康信息

// build.gradle.kts（Kotlin DSL）

// 移除（如果有）：
// implementation("io.micrometer:micrometer-registry-otlp")

// 添加：
implementation("io.micrometer:micrometer-registry-prometheus")
// Spring Boot BOM 已管理版本，无需指定

# prometheus.yml
scrape_configs:
  - job_name: 'hello-service'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['hello-service:18080']

  - job_name: 'user-service'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['user-service:18081']

# otel-collector-config.yaml
processors:
  attributes/sanitize:
    actions:
      - key: user.id
        action: hash      # 对用户 ID 做单向哈希，保留可关联性，去除可识别性
      - key: user.email
        action: delete    # 直接删除邮箱等敏感字段
      - key: user.phone
        action: delete

processors:
  batch:
    timeout: 5s            # 最多等 5s 凑一批
    send_batch_size: 1024  # 或达到 1024 条就发送

  memory_limiter:
    check_interval: 1s
    limit_mib: 256         # 防止 Collector OOM