Next.js OpenTelemetry追踪问题：Grafana Trace表字段显示异常

核心原因 #

这是Tempo与Grafana在处理分批到达的追踪数据时的临时显示问题：

• 追踪的根Span通常是最后被接收和处理的，而Grafana的追踪列表会优先渲染已收到的Span数据。此时根Span尚未到达，就会显示root span not yet received，Name字段也因缺少根Span的名称而为空。
• 当完整追踪数据全部落地后，点击Trace ID能看到正确信息，说明数据最终是完整的，只是列表视图的渲染时机早于根Span的到达时间。

可能的触发因素 #

• Next.js的SSR/API路由生成的追踪Span可能被拆分成多批发送，根Span的发送时机晚于子Span。
• OpenTelemetry默认的批量导出策略（定时批量发送），导致根Span和子Span不在同一批次到达Tempo。
• Grafana Agent的转发或缓存策略，延迟了根Span的处理速度。

解决办法 #

1. 调整OpenTelemetry批量导出参数 #

修改Span的批量处理器配置，让尽可能多的Span在同一批次发送，减少分批情况：

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { PeriodicExportingMetricReader, ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');

const traceExporter = new OTLPTraceExporter();
// 自定义批量处理器，优化发送时机
const spanProcessor = new BatchSpanProcessor(traceExporter, {
  maxQueueSize: 1000,
  scheduledDelayMillis: 300, // 缩短批量发送间隔
  exportTimeoutMillis: 2000,
  maxExportBatchSize: 500,
});

const sdk = new NodeSDK({
  spanProcessor: spanProcessor, // 替换原traceExporter配置
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter(),
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': { enabled: false },
      '@opentelemetry/instrumentation-http': {
        requestHook: (span, request) => {
          span.updateName(`${request.method} ${request.url || request.path}`);
          if (request.path) {
            span.setAttribute('http.route', request.path);
          }
        },
      },
    }),
  ],
});

sdk.start();

2. 显式标记根Span的服务名与属性 #

确保根Span的核心属性被正确设置，避免Tempo识别根Span时出错：
在HTTP instrumentation的requestHook中添加：

span.setAttribute('service.name', 'your-nextjs-service'); // 替换为你的服务名
// 确保根Span的标记
if (!span.parentSpanId) {
  span.setAttribute('span.kind', 'SERVER');
}

3. 优化Grafana Agent的Tempo转发配置 #

调整Agent的批量发送参数，加快Span的聚合和转发速度：

tempo:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
  remote_write:
    - endpoint: tempo:4317
      batch:
        send_batch_size: 1000
        send_batch_max_size: 1000
        timeout: 3s # 缩短批量等待时间

4. 启用Next.js专属Instrumentation #

确保使用Next.js的官方Instrumentation，避免自动生成的Span混乱：

getNodeAutoInstrumentations({
  '@opentelemetry/instrumentation-fs': { enabled: false },
  '@opentelemetry/instrumentation-next': { enabled: true }, // 启用Next.js专属 instrumentation
  '@opentelemetry/instrumentation-http': {
    // 你的现有配置
  },
});

总结 #

这个问题属于追踪数据到达顺序导致的临时显示异常，并非数据丢失。通过优化批量发送策略、确保根Span属性正确，大部分情况下可以缓解或消除该现象。如果问题持续，可排查Grafana Agent的日志，确认是否存在Span转发延迟或丢包情况。

内容的提问来源于stack exchange，提问作者bradb123