OpenTelemetry 日志信号进入生产后如何和 trace_id 对齐

线上排查一个慢请求时，trace 页面里有完整的服务调用链，日志检索却只能靠时间和模糊关键词翻找，通常不是 OpenTelemetry “没有日志能力”，而是日志没有拿到活动上下文，或者拿到了却在格式转换时丢了字段。真正要对齐的是同一次执行上下文：日志里的 trace_id 应该指向这条 trace，span_id 再把日志定位到具体操作。

官方入口：https://opentelemetry.io/

步骤一：先判断是没有 TraceId 还是字段被吞掉

值班时先固定一个真实请求，分别拿到 trace 和日志。若 trace 本身存在，但同一时间窗口的日志完全没有关联字段，优先看日志调用是否发生在活动 Span 内；若应用输出有字段而日志平台没有，问题就在采集、解析或字段映射阶段。

不要先批量改查询语句。OpenTelemetry 日志模型把 TraceId 定义为请求 trace ID，SpanId 定义为具体 span；如果当前执行没有分配 trace，这两个字段为空是正常结果。

步骤二：统一生产日志的关联字段

OTLP LogRecord 使用 TraceId、SpanId 和 TraceFlags 这样的顶层字段。若落地为传统 JSON，兼容规范建议改成顶层小写的 trace_id、span_id、trace_flags，而不是把它们埋在一段不可解析的 message 文本里。这样日志平台才能建立字段索引，跨语言服务也能使用同一查询条件。

func fieldsFromContext(ctx context.Context) map[string]string {
    // 只从当前上下文读取 Span，不在没有链路时伪造 ID。
    sc := trace.SpanContextFromContext(ctx)
    if !sc.IsValid() {
        return nil
    }
    // 非 OTLP JSON 使用规范约定的小写十六进制字段名。
    return map[string]string{
        "trace_id":    sc.TraceID().String(),
        "span_id":     sc.SpanID().String(),
        "trace_flags": fmt.Sprintf("%02x", byte(sc.TraceFlags())),
    }
}

示例只负责生成关联字段，实际日志库还要把这组字段作为结构化属性输出。空值不要写成全零字符串，否则监控面板会误以为所有日志都来自同一条 trace。

步骤三：沿着请求和异步边界传递上下文

很多“偶尔为空”并不是格式问题，而是 context.Context 没有穿过边界。HTTP handler 调用 service 时要继续传递 ctx；启动 goroutine 时要明确它使用的是当前请求上下文还是一个脱离请求生命周期的后台上下文。消息队列消费者、定时任务和重试任务如果没有父 trace，也应记录自己的新执行边界，而不是复制上一次请求的 ID。

跨服务传播还要检查 W3C Trace Context 是否被代理或网关剥掉。能在入口服务看到 trace_id，不代表下游一定沿用了它；把入口、客户端、服务端三处日志放在同一条 trace 下比较，定位会快很多。

步骤四：准备兼容和回滚路径

上线字段增强前，确认旧的日志解析器是否只接受固定字段集合。有些规则把整条 JSON 重新拼成 message，新增字段会被忽略；这时先在 Collector 中保留原始 body，再把关联字段提升为索引字段。若告警查询依赖旧键名，可以做短期双写或别名映射，不要直接删除旧字段。

回滚开关应只关闭关联字段增强，不要关闭 trace 采集本身。若新配置导致采集器错误率升高，恢复上一版 pipeline，保留原始日志样本和变更时间，便于确认是 exporter、解析器还是后端索引的兼容问题。

步骤五：用关联率和告警确认结果

灰度完成后至少看三项：日志中 trace_id 非空的比例、同一请求在多个服务中的 ID 一致率、以及从日志跳转到 trace 的查询成功率。再结合 Collector 的 dropped records、解析错误和后端采样策略判断结果。OpenTelemetry Go 文档目前将日志组件标为 Release Candidate，生产环境更需要固定版本、记录配置变更，并把采集链路当成整体观察。

最终检查可以简化成一句话：拿一条真实 trace，能否用它的 trace_id 找到关键日志，并且能从关键日志回到正确的 span。如果只能查到一串相似时间的日志，说明对齐还没有完成。

常见问题

日志里只有 span_id，没有 trace_id，可以接受吗？

不建议。规范说明 SpanId 出现时应同时有 TraceId；缺少后者会让日志无法按整条请求聚合，优先修正生成或映射链路。

trace_id 一定要写成大写字段 TraceId 吗？

不一定。OTLP LogRecord 使用 TraceId；传统 JSON 兼容格式建议使用顶层小写 trace_id，关键是整个采集和查询链路保持一致。

没有活动 Span 的定时任务怎么办？

为任务创建独立的根 Span，或明确记录“无请求上下文”的任务日志；不要把上一个请求的 trace_id 复制过来。