OpenTelemetry日志与Trace关联字段的落地清单

OpenTelemetry把日志和Trace放进同一套可观测性语境后，真正容易出问题的不是“有没有采集”，而是字段能不能在整条链路上保持一致。落地时建议固定 trace_id、span_id、trace_flags、service.name 四组信息：应用从当前上下文读取标识，日志用结构化字段输出，Collector负责解析和补充资源，后端再按同一个Trace检索。

官方资料入口：https://opentelemetry.io/docs/specs/otel/logs/data-model/

下面这份清单适合已经有结构化日志、正在接入OpenTelemetry，或需要排查“Trace能看到但日志跳不过去”的服务。文中的图均为静态说明图，不是实际软件截图或运行证据。

先固定可关联字段

先把字段协议写成团队约定，不要让每个服务自行发明 requestId、traceId 或大小写不同的别名。OpenTelemetry日志数据模型把TraceId和SpanId作为Trace上下文，Resource则描述产生遥测数据的实体，因此它们解决的是两类不同问题。

非OTLP JSON日志建议把前三个关联字段放在顶层，避免埋在自由文本里。这样查询系统不必先用正则拆日志，也能直接按字段过滤。

应用侧让日志拿到当前Span

字段统一之后，第二个关键点是来源统一。应用应从请求上下文中的当前Span读取标识，而不是在打印日志时重新生成一组随机ID。跨服务调用则依赖W3C TraceContext传播，入口服务接收上下文，下游服务创建子Span，日志自然沿着当前上下文获得同一个 trace_id。

下面是一个简化的Go示例，重点是“先让Span进入Context，再让日志读取Context”。实际项目可替换成已有的结构化日志库：

func logFields(ctx context.Context, body string) map[string]any {
    span := trace.SpanFromContext(ctx)
    sc := span.SpanContext()

    // 无有效Span时保留空值，避免伪造一组看似可关联的ID。
    fields := map[string]any{"body": body}
    if !sc.IsValid() {
        return fields
    }
    // 使用标准十六进制形式，和非OTLP日志字段约定保持一致。
    fields["trace_id"] = sc.TraceID().String()
    fields["span_id"] = sc.SpanID().String()
    fields["trace_flags"] = fmt.Sprintf("%02x", byte(sc.TraceFlags()))
    return fields
}

异步任务要特别小心：如果把任务丢到队列后再由另一个进程执行，不能假设原进程的内存上下文会自动跟过去。应在消息元数据中传播标准TraceContext，消费端提取后再创建自己的Span；对于定时任务或脱离请求的后台作业，则允许没有TraceId，并用稳定的任务ID、队列名和资源字段帮助定位。

Collector只做统一，不重造ID

Collector的职责是接收、解析、补充Resource和导出，不应该在字段缺失时随意生成新的 trace_id。一旦采集层生成另一套ID，日志与Trace在后端看起来都“有值”，却无法互相跳转。

receivers:
  filelog:
    include: [/var/log/app/*.json]
    operators:
      - type: json_parser
        parse_from: body
        # 把JSON日志解析成可查询的结构化字段。
        parse_to: attributes

processors:
  resource:
    attributes:
      - key: service.name
        value: checkout-api
        action: upsert
        # 资源信息描述产生日志的服务，不替代Trace上下文。

service:
  pipelines:
    logs:
      receivers: [filelog]
      processors: [resource]
      exporters: [otlp]

如果旧日志已经把关联信息写在文本中，可以在Collector中做一次明确的解析映射，但要记录“字段从哪里来、解析失败时怎么办”。新应用优先输出结构化JSON或直接使用OpenTelemetry日志管线，减少采集端的猜测。

上线前用三条样例验收

不要只检查Collector进程是运行状态。拿一条能经过入口服务和下游服务的请求，分别在日志和Trace后端核对：

1. 入口日志与入口Span的 trace_id 完全一致，格式为小写十六进制。
2. 下游日志仍使用同一个 trace_id，但 span_id 对应下游自己的Span，而不是入口Span。
3. 每条日志都能按 service.name 区分来源；如果是非请求日志，则明确标记为无当前Span，而不是填入虚假ID。

验收时还要故意覆盖采样关闭、跨线程/异步任务、下游调用失败和旧格式日志四个边界。采样策略可能让某些Span没有被后端保存，但这不等于字段传播失败；应分别看应用输出、Collector处理和后端采样结果。

几个容易误判的边界

第一，trace_id 相同不代表两个日志属于同一个操作，细粒度定位还要看 span_id。第二，只有 span_id 而没有 trace_id 的记录不应视为完整关联，官方数据模型也把TraceId作为SpanId的配套上下文。第三，Resource字段描述服务、容器或进程，不能拿它替代请求级Trace字段。第四，日志正文里的“trace_id=...”只是文本，除非采集器明确解析，否则不能当作结构化字段查询。

最终可以把这份清单固化成发布门禁：字段命名固定、上下文来源唯一、Collector不重造ID、跨服务样例可回溯、无上下文场景显式为空。这样新增服务时只需检查协议和验收样例，不必重新猜每个后端的跳转规则。

相关问题

为什么日志里有trace_id，后端仍然跳不到Trace？ 常见原因是字段被当成普通文本、大小写或长度不符合后端约定，或者日志使用的是重新生成的请求ID。先分别比较应用日志、Collector输出和Trace中的原始字段。

没有当前Span的日志要不要强行补trace_id？ 不要。后台任务、启动日志和系统日志可能没有请求上下文，应保留空值并补充任务、主机、服务等Resource信息，避免制造错误关联。