Micrometer 中如何正确暴露高基数订单数据到 Prometheus

Micrometer 中如何正确暴露高基数订单数据到 Prometheus

在微服务观测领域，一个常见的误区是试图将业务对象列表直接注册为监控指标。比如，想把一批List直接扔给Micrometer，期望每个订单的ID、状态、国家都成为一个漂亮的标签。想法很直观，但后果可能很严重。

Micrometer 不支持直接注册对象列表，尤其当 ID 等字段构成高基数标签时，会引发 JVM 内存暴涨和 Prometheus 存储/查询性能崩溃，应改用低基数聚合指标或外部导出方案。

这并非功能上的缺失，而是设计上的主动规避。在 Micrometer + Prometheus 这套观测体系里，MeterRegistry的核心职责是收集可聚合、低基数、语义明确的观测信号——比如计数器、计时器、仪表盘数值。它本质上是一个高度优化的“仪表盘”，而不是用来序列化完整业务实体的数据仓库。

我们来看看那种“直观但危险”的设想：

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

问题出在哪里？关键在于标签的“基数”。想象一下，如果订单ID作为标签值，每小时新增1万个订单，Prometheus就会为每个唯一的ID组合创建一条独立的时间序列。一天下来，光是这个指标就可能产生超过24万条时间序列。这直接踩中了Prometheus的“高压线”，会导致其存储空间急剧膨胀、查询性能断崖式下跌，甚至拖垮整个监控系统。

那么，正确的做法是什么？

✅ 推荐替代方案

1. 按业务维度聚合（首选）
   放弃展示每一条明细，转而统计关键维度的组合。这才是监控指标该干的事。例如，我们可以定时（比如每5分钟）从数据库查询，按国家和状态分组统计订单数量：

   @Scheduled(fixedRate = 300_000) // 每5分钟刷新
   public void reportOrderStats(MeterRegistry registry) {
       Map, Long> counts = orderRepository.countByCountryAndStatus();
       counts.forEach((tags, count) ->
            Counter.builder("orders.by_country_status")
                  .tag("country", tags.get(0))
                  .tag("status", tags.get(1))
                  .register(registry)
                  .increment(count)
       );
   }

   这样输出的指标既安全又具备可聚合性：

   orders_by_country_status{app="my-api",country="DK",status="ACTIVE"} 127
   orders_by_country_status{app="my-api",country="DK",status="ARCHIVED"} 42
   orders_by_country_status{app="my-api",country="DE",status="ACTIVE"} 89

2. 使用 Micrometer 的 TimeGauge 表达“当前活跃数”
   如果只是想在Grafana上看到一个实时变化的“当前活跃订单总数”，而不是每条记录，那么TimeGauge是个好选择。它适合表达一个随时间变化的瞬时值：

   private final AtomicInteger activeOrderCount = new AtomicInteger(0);
   
   @PostConstruct
   public void initActiveCount() {
       TimeGauge.builder("orders.active.count", activeOrderCount, AtomicInteger::get)
                 .description("Current number of ACTIVE orders")
                 .register(registry);
   }
   
   @Scheduled(fixedRate = 60_000)
   public void refreshActiveCount() {
       activeOrderCount.set(orderRepository.countByStatus(Status.ACTIVE));
   }

3. 完全规避 Prometheus：导出为 OpenMetrics 文本端点（进阶）
   如果因为调试、审计等特殊需求，必须保留每条订单的明细信息怎么办？一个进阶方案是绕过Micrometer，自己实现一个端点来返回标准的OpenMetrics格式文本，然后让Prometheus把它当作一个静态配置来抓取：

   @GetMapping(value = "/actuator/orders-metrics", produces = TEXT_PLAIN_VALUE)
   public String exportOrdersAsMetrics() {
       return orderRepository.findAllActive().stream()
               .map(o -> String.format(
                   "my_orders{app=\"my-api\",id=\"%s\",country=\"%s\",status=\"%s\"} 1",
                   escape(o.getId()), escape(o.getCountry().name()), escape(o.getStatus().name())
               ))
               .collect(Collectors.joining("\n")) + "\n";
   }

   需要特别警惕的是，这种方式完全脱离了Micrometer的生命周期管理。你必须自己处理抓取频率、错误重试，并且要清醒地认识到它依然存在高基数风险。因此，仅建议在数据量极小、抓取频率很低的特定场景下使用。

关键总结

• ❌ 绝对禁止将唯一ID、UUID、邮箱、手机号等高基数字段作为Prometheus的标签。
• ✅ 优先聚合与降维：使用count、group by，按国家、状态、日期等有限维度进行统计。
• ✅ 明细数据另寻出路：如果需要查询具体订单信息，应该让Grafana去关联PostgreSQL等业务数据库，或者将日志发送到Elasticsearch、Loki这类专用的事件存储系统。
• ✅ 规范指标定义：所有自定义指标务必添加清晰的description，并打上app、env、instance等环境上下文标签。

说到底，Micrometer是观测管道的“仪表盘”，而Prometheus是高效的时序数据库。让对的工具做对的事，才能构建出既稳定又可扩展的可观测性体系。