Micrometer 中无法直接注册对象列表：高基数标签的风险与替代方案

Micrometer 不支持将对象列表（如 List）直接注册为指标，因其设计目标是聚合度量而非存储原始业务数据；使用订单 ID 等高基数字段作为标签会导致 Prometheus 内存激增、查询变慢甚至崩溃。

在微服务监控领域，一个常见的误区是试图把业务数据直接塞进指标系统。比如，你手头有一份订单列表，想通过 Micrometer 和 Prometheus 实时监控每笔订单的状态。想法很自然，但这条路，从一开始就走错了方向。

Micrometer 的设计初衷，是管理和注册聚合型指标——比如计数器、仪表盘、计时器这些。它的 MeterRegistry 可不是用来序列化或导出原始业务实体的。你可能会期望生成下面这样的 Prometheus 数据：

my_orders{app="my-api", id="my_id_1", country="DK", status="ACTIVE"}
my_orders{app="my-api", id="my_id_2", country="DK", status="ACTIVE"}

看起来一目了然，对吧？但问题恰恰出在这里。订单 ID 是典型的高基数标签。基数有多高？假设系统每小时新增一万个订单，一天下来，Prometheus 里就会凭空多出近 24 万个唯一的时间序列。这个数字带来的连锁反应是灾难性的：

• 在 JVM 层面，MeterRegistry 会为每一个独特的标签组合创建独立的 Meter 实例，这无异于埋下了内存泄漏的种子，并给垃圾回收带来巨大压力。
• 在 Prometheus 端，时间序列数据库的存储会急剧膨胀，查询响应变得迟缓，数据抓取可能超时，严重时甚至直接导致内存溢出而崩溃。
• 到了 Grafana 这一层，你不仅无法高效地进行数据下钻或过滤，更重要的是，这完全违背了监控指标“应可聚合”的核心设计原则。

正确的替代方案

✅ 方案一：按维度聚合统计（首选方案）

正确的思路是“聚合”，而非“枚举”。我们应该使用带标签的计数器或分布摘要，按照国家、状态这类低基数维度进行统计，而不是为每一条记录创建指标。

@Component
public class OrderMetrics {
    private final Counter activeOrdersByCountry;
    private final Counter activeOrdersByStatus;

    public OrderMetrics(MeterRegistry registry) {
        this.activeOrdersByCountry = Counter.builder("orders.active.by.country")
                .description("Count of active orders grouped by country")
                .tag("app", "my-api")
                .register(registry);
        this.activeOrdersByStatus = Counter.builder("orders.active.by.status")
                .description("Count of active orders grouped by status")
                .tag("app", "my-api")
                .register(registry);
    }

    public void recordOrders(List orders) {
        orders.stream()
                .filter(order -> "ACTIVE".equals(order.getStatus().name()))
                .forEach(order -> {
                    activeOrdersByCountry.tag("country", order.getCountry().name()).increment();
                    activeOrdersByStatus.tag("status", order.getStatus().name()).increment();
                });
    }
}

这样一来，在 Prometheus 中，你可以通过聚合查询轻松获取洞察，例如：

sum by (country) (orders_active_by_country{app="my-api"})

✅ 方案二：导出为自定义 /actuator/prometheus 扩展（限特定场景）

如果确实需要在调试等特殊场景下暴露更详细（但仍非明细）的数据，可以通过 PrometheusMeterRegistry 的收集器机制注入自定义 Collector。这里有个关键前提：绝对禁止包含 ID 标签，只允许使用预先定义好的低基数维度。

@Bean
public Collector customOrderCollector(MeterRegistry registry) {
    return new Collector() {
        @Override
        public List collect() {
            List mfs = new ArrayList<>();
            GaugeMetricFamily ordersGauge = new GaugeMetricFamily(
                "orders_summary",
                "Summary of orders by country and status (no ID)",
                Arrays.asList("app", "country", "status")
            );
            // 示例：从数据库或缓存获取聚合结果（非实时 List）
            Map summary = getAggregatedOrderCounts(); // 例如：{"DK|ACTIVE": 127}
            summary.forEach((key, count) -> {
                String[] parts = key.split("\|");
                ordersGauge.addSample(count.doubleValue(),
                     Arrays.asList("my-api", parts[0], parts[1]));
            });
            mfs.add(ordersGauge);
            return mfs;
        }
    };
}

⚠️ 绝对禁止的做法

下面这段代码，堪称“监控系统的自杀式攻击”，请务必远离：

// ❌ 危险！生成无限时间序列
orders.forEach(order ->
    Gauge.builder("my_orders", () -> 1.0)
         .tag("id", order.getId())          // ← 高基数！致命陷阱
         .tag("country", order.getCountry().name())
         .tag("status", order.getStatus().name())
         .register(registry));

总结

• 别把 Micrometer 当数据库用。它的职责是度量聚合，而非存储或枚举具体的业务对象。
• 牢记指标设计的黄金法则：使用低基数标签，并进行高频聚合。这是保证监控系统稳定、高效的基石。
• 如果需要在 Grafana 上展示一张详细的订单列表，正确的做法是开发独立的查询 API（例如 /api/orders?status=ACTIVE），并搭配相应的数据库数据源插件（如 PostgreSQL、MySQL），而不是强行让 Prometheus 去干它不擅长的事。
• 最后，时刻将 Prometheus 官方的警示放在心上：High Cardinality Considerations（高基数考量）。这绝非危言耸听，而是无数踩坑经验换来的教训。