智能微服务可观测性质量门禁：OpenTelemetry Trace 污染防线与 Prometheus 告警指标 Review 清单

智能微服务可观测性质量门禁：OpenTelemetry Trace 污染防线与 Prometheus 告警指标 Review 清单

可观测性代码评审要先检查 Trace 上下文、指标标签和采样策略是否一致，再看告警能否关联到可执行的排障证据。本文的清单适合按服务风险裁剪。

然而，查询界面转了半天圈，最终弹出了 Collector Buffer Full – 503 Service Unavailable。

原因在于：开发人员在接入大模型智能 Agent（Tool Calling）功能时，直接在递归调用的循环内部无节制地创建 OpenTelemetry Tracer.spanBuilder()。

模型发生非确定性死循环后，单次智能问答请求在不到 10 秒内向 Collector 狂喷了 35,000 个超长 Span 报文，直接冲垮了 OpenTelemetry Collector 节点的内存缓冲区，导致全公司所有微服务的 Trace 日志整整中断了 40 分钟。

在推进微服务智能化与可观测性（Observability）建设的过程中，如果缺乏代码层的质量门禁（Quality Gate）与 Code Review 规范，失控的 Trace 污染与高基数（High Cardinality）Prometheus 指标不仅无法帮助定位故障，反而会成为拖垮生产系统的元凶。

1. Trace 污染与高基数 Metrics 崩溃架构

在传统的微服务体系中，一个 RPC 请求经过的 Span 数量是固定的（一般在 10 ~ 50 个之间）。

但在集成了 LLM、向量数据库与智能 Agent 编排的微服务中，一次请求可能会触发数十次 Tool Calling 递归、多轮 RAG 检索与迭代重试。

如果代码层缺乏采样（Sampling）与 Span 数量硬限制门禁，就会引发严重的“可观测性数据爆炸”：

除了 Trace 爆炸外，另一个常见的质量漏洞是在 Prometheus 自定义 Counter / Gauge 指标中，误将变长参数（如 user_id、order_id、prompt_hash）作为 Metric Label 写入。

这会导致 Prometheus 的 Index 内部序列呈百万级爆炸增长（即高基数问题），最终导致 Mimir 或 Prometheus TSDB 数据库直接 OOM 崩溃。

2. 可观测性现场诊断与分析指令集

在可观测性管线发生阻塞或数据丢失时，需要使用命令行诊断工具分析 Collector 的收发状态与 JVM 内 Trace Agent 的占用情况。

2.1 查看 OpenTelemetry Collector 实时 drop 指标

通过 curl 访问 OTel Collector 的 8888 监控端口：

# 1. 查询 OTel Collector 内部接收与丢弃的 Span 统计
curl -s "${OTEL_COLLECTOR_METRICS_URL}" | grep -E "otelcol_receiver_refused_spans|otelcol_processor_dropped_spans"

# 2. 查看内存限流处理器 (Memory Limiter) 的触发状态
curl -s "${OTEL_COLLECTOR_METRICS_URL}" | grep "otelcol_processor_memory_limiter"

如果 otelcol_processor_dropped_spans 持续上升，说明客户端发送的 Trace 报文已经严重超越了 Collector 的承载上限。

2.2 诊断 Java 应用内 OpenTelemetry 内存分配

使用 jcmd 查看 OTel Java Agent 在 JVM 内存中持有的 BatchSpanProcessor 队列：

# 1. 查看 JVM 线程中 OTel exporter 线程状态
jstack <pid> | grep -A 10 "BatchSpanProcessor"

# 2. 统计 OpenTelemetry ReadableSpan 实例在堆内存中的占用数
jcmd <pid> GC.class_histogram | grep -E "opentelemetry|SdkSpan" | head -n 15

3. 生产级 Safe Trace 采样器与高基数 Label 清理代码

为了防止失控的代码打爆可观测性系统，必须在应用层提供强约束的 Trace 计数限制器与 Metrics Label 规范化 Filter。

package com.example.observability.filter;

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.sdk.trace.ReadableSpan;
import io.opentelemetry.sdk.trace.data.SpanData;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.common.CompletableResultCode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Set;
import java.util.concurrent.atomic.AtomicInteger;

/**
* 生产级 Safe Span Exporter 包装器：强制管控单请求 Span 产生上限，并滤除高基数危险 Label
*/
public class SafeBoundarySpanExporter implements SpanExporter {

private static final Logger log = LoggerFactory.getLogger(SafeBoundarySpanExporter.class);

// 【CR 规约 1】：单次 RPC / 任务请求中，允许导出的最大 Span 数量上限 (防止 Agent 递归死循环污染)
private static final int MAX_SPANS_PER_BATCH = 100;

// 禁止传入 Prometheus / Trace Label 的高基数属性黑名单
private static final Set<String> HIGH_CARDINALITY_KEYS = Set.of(
"user_id", "order_id", "prompt_text", "api_token", "device_id"
);

private final SpanExporter delegateExporter;

public SafeBoundarySpanExporter(SpanExporter delegateExporter) {
this.delegateExporter = delegateExporter;
}

@Override
public CompletableResultCode export(Collection<SpanData> spans) {
List<SpanData> sanitizedSpans = new ArrayList<>();
AtomicInteger count = new AtomicInteger(0);

for (SpanData span : spans) {
// 1. 超过最大额度的 Span 强制 Drop，防止打爆 Collector
if (count.incrementAndGet() > MAX_SPANS_PER_BATCH) {
log.warn("Exceeded max allowed Spans per batch ({}). Dropping excess trace span: {}",
MAX_SPANS_PER_BATCH, span.getName());
continue;
}

// 2. 高基数 Label / 敏感隐私属性安全过滤
SpanData sanitizedSpan = sanitizeHighCardinalityAttributes(span);
sanitizedSpans.add(sanitizedSpan);
}

return delegateExporter.export(sanitizedSanitizedSpans);
}

private SpanData sanitizeHighCardinalityAttributes(SpanData span) {
// 在此处过滤掉用户 ID、订单号等容易导致 TSDB 高基数爆炸的属性
Attributes originalAttrs = span.getAttributes();
Attributes sanitizedAttrs = originalAttrs.toBuilder()
.removeIf(attributeKey -> HIGH_CARDINALITY_KEYS.contains(attributeKey.getKey()))
.build();

// 重新构建清洗后的 SpanData (此处为简化示意)
return span;
}

@Override
public CompletableResultCode flush() {
return delegateExporter.flush();
}

@Override
public CompletableResultCode shutdown() {
return delegateExporter.shutdown();
}
}

4. 可观测性代码 Review 10 条硬核门禁清单

为了保证可观测性系统的稳定高效，团队在 Pull Request 评审中必须严格把守以下 10 条 Check List：