Micrometer 可观测性

类比理解：
  SLF4J      : 日志门面，后端 Logback/Log4j2 可换
  Micrometer : 指标门面，后端 Prometheus/Datadog/OTLP 可换

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

@Service
public class OrderService {
    private final Counter created;
    private final Timer createTimer;
    private final AtomicInteger queueSize = new AtomicInteger();

    public OrderService(MeterRegistry registry) {
        this.created = Counter.builder("order.created.total")
                .description("创建的订单总数")
                .tag("type", "normal")
                .register(registry);
        this.createTimer = Timer.builder("order.create.duration")
                .description("订单创建耗时")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(registry);

        // Gauge 必须持有被观测对象的强引用，否则会被 GC 回收
        Gauge.builder("order.queue.size", queueSize, AtomicInteger::get)
             .description("待处理订单队列长度")
             .register(registry);
    }

    public Order create(CreateCmd cmd) {
        return createTimer.record(() -> {          // 自动计时 + 异常也记录
            Order o = doCreate(cmd);
            created.increment();
            return o;
        });
    }
}

Counter vs Gauge 的常见误用：
  错误：用 Counter 记录「当前在线人数」（会降，Counter 只能增）
  正确：用 Gauge 或直接读业务指标
  错误：手动给 Timer 加标签 "result=success/failure" 让基数翻倍
  正确：失败单独一个 Counter，避免同一指标标签爆炸

// 危险：用用户 ID 作标签 → 每条时间序列 × 用户数
registry.counter("api.request", "userId", userId).increment();

// 危险：用 URL 全路径作标签 → 每个 ID 一个序列
registry.counter("http.request", "uri", "/order/12345").increment();

# Spring Boot 3 默认已做 URI 模板化，避免路径变量撑爆基数
management:
  metrics:
    web:
      server:
        request:
          autotime:
            enabled: true

基数治理三原则：
  1. 标签值必须来自「有限枚举」，不能是 ID/时间戳/自由文本
  2. 路径用模板（/order/{id}）而非实际值
  3. 高基数需求改用「追踪（trace）」或「日志」承载，别塞进指标
  4. 上线前估算：指标数 × 标签组合数 × 实例数，超过 10 万就要警惕

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  metrics:
    tags:
      application: ${spring.application.name}
    distribution:
      percentiles-histogram:
        http.server.requests: true   # 输出直方图，供后端算分位
      slo:
        http.server.requests: 100ms,500ms,1s

# 查看所有指标名
curl -s localhost:8080/actuator/metrics | jq '.names | length'

# 查看某指标及其标签
curl -s 'localhost:8080/actuator/metrics/http.server.requests?tag=uri:/order/{id}'

# Prometheus 拉取端点
curl -s localhost:8080/actuator/prometheus | grep http_server_requests

开箱即用的指标族：
  jvm.memory.used / jvm.gc.pause / jvm.threads.live
  http.server.requests（含 uri/method/status/outcome 标签）
  hikaricp.connections.*（连接池）
  spring.data.repository.invocations
  cache.gets / cache.puts
  logback.events

@Configuration
public class MetricsConfig {
    // 注册切面，让注解生效
    @Bean
    public TimedAspect timedAspect(MeterRegistry registry) {
        return new TimedAspect(registry);
    }
}

@Service
public class PaymentService {
    @Timed(value = "payment.process", percentiles = {0.95, 0.99},
           extraTags = {"channel", "alipay"})
    public Result process(PaymentCmd cmd) { /* ... */ }

    @Counted(value = "payment.retry.total", recordFailuresOnly = false)
    public void retry(String id) { /* ... */ }
}

注解埋点的注意点：
  1. @Timed 依赖 AOP 代理 → 自调用（this.method()）不生效
  2. 类必须是 Spring Bean
  3. extraTags 是静态值，不能放动态 ID
  4. 生产更推荐 Observation API（见下节），注解适合快速接入

@Service
public class InventoryService {
    private final ObservationRegistry registry;

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

    public Stock check(String sku) {
        Observation obs = Observation.createNotStarted("inventory.check", registry)
                .lowCardinalityKeyValue("warehouse", "cn-east")
                .highCardinalityKeyValue("sku", sku);   // 只进 trace，不进 metric
        return obs.observe(() -> doCheck(sku));
    }
}

低基数 vs 高基数标签的自动分流：
  lowCardinalityKeyValue  → 进入指标（metric），要求有限枚举
  highCardinalityKeyValue → 进入追踪（span），可放 ID
  这一设计从根上避免「把 traceId 塞进指标」的灾难

// 用 ObservationConvention 统一定义标准标签
public class InventoryConvention implements ObservationConvention<InventoryContext> {
    @Override
    public KeyValues getLowCardinalityKeyValues(InventoryContext ctx) {
        return KeyValues.of("warehouse", ctx.warehouse());
    }
    @Override
    public String getName() { return "inventory.check"; }
}

# Spring Boot 3 已自动为 HTTP/RestTemplate/WebClient 埋 Observation
management:
  observations:
    key-values:
      region: cn-east

# prometheus.yml
scrape_configs:
  - job_name: 'spring-app'
    metrics_path: '/actuator/prometheus'
    scrape_interval: 15s
    static_configs:
      - targets: ['app:8080']

指标暴露格式：
  # HELP http_server_requests_seconds
  # TYPE http_server_requests_seconds histogram
  http_server_requests_seconds_bucket{uri="/order/{id}",le="0.1"} 1024
  http_server_requests_seconds_bucket{uri="/order/{id}",le="+Inf"} 1200
  http_server_requests_seconds_count{uri="/order/{id}"} 1200
  http_server_requests_seconds_sum{uri="/order/{id}"} 42.5

# 常见查询
# QPS
rate(http_server_requests_seconds_count{application="order"}[1m])

# P99 延迟（基于直方图）
histogram_quantile(0.99,
  sum(rate(http_server_requests_seconds_bucket{application="order"}[5m])) by (le, uri))

# 错误率
sum(rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
  / sum(rate(http_server_requests_seconds_count[5m]))

Exemplar（样本）：
  在指标里携带 traceId 样本，Grafana 可从延迟毛刺一键跳转到对应 trace
  需要 Micrometer Tracing + OTel/Brave 与 Prometheus 3.x 支持
  配置：management.tracing.enabled=true，配合 observation

上线检查清单：
  1. 每个自定义指标都问：谁消费它？告警还是看板？
  2. 估算基数：指标数 × 标签组合 × 实例数 < 10 万
  3. 统一标签：application / instance / region 由配置注入，不在代码里写
  4. 关键路径埋 Timer，失败路径埋 Counter，别用同一个指标的标签区分
  5. 直方图 + SLO 分桶按需开启，避免全量开启导致存储暴涨
  6. 指标与追踪的 traceId 用 Exemplar 打通