OpenTelemetry Logs 信号怎样与 traces 关联

在高并发服务里，traces 能告诉你一次请求经过了哪些 span，Logs 则保留错误上下文、业务对象和处理细节。两者如果只靠时间窗口或服务名拼接，流量一大就会出现“看见日志，却不知道它属于哪条链路”的问题。更稳妥的做法是沿用当前请求的 SpanContext，把 TraceId、SpanId 和 Resource 一起写入结构化日志，再让 Collector 分别处理 Logs 与 traces。

官方地址：https://opentelemetry.io/docs/specs/otel/logs/

关联的关键不是给日志额外造一个 request_id，而是让日志读取当前请求上下文中的 TraceId 和 SpanId，并把这些字段作为 LogRecord 的一等数据保留下来。

OpenTelemetry 的 Logs 规范明确把日志与 traces 的关联建立在执行上下文和资源上下文之上。下面按“旧链路为什么会失效、字段如何落地、Collector 怎样分流、上线后看什么信号”的顺序展开。

先解决跨服务链路的关联键问题

旧式链路常见三种关联方式：按时间相邻、按主机或服务名过滤、在日志文本中手工拼接业务流水号。低流量时它们看起来够用，到了高并发、重试和异步调用场景就会互相干扰：同一毫秒内可能有很多请求，重试会产生新的 span，业务流水号又未必跨服务传递。

TraceId 适合表示一次端到端请求，SpanId 适合定位这次请求中的某个处理阶段。服务 A 调用服务 B 时，子 span 会继续属于同一个 Trace；服务 B 产生的日志只要读取它所在的当前 context，就能把自身细节挂到对应 span 上。这样查询入口从“猜哪几行日志”变成“先定位 Trace，再展开相关日志”。

这里要区分两个概念：TraceId 是跨服务的主关联键，SpanId 是局部定位键。不能在每次打印日志时随机生成新的 TraceId，否则日志数量虽然增加，关联能力反而被切断。

在请求边界读取当前 SpanContext

应用层最重要的动作是让日志调用拿到请求 context。以 Go 为例，下面的辅助函数只负责从当前 context 提取关联字段；真正的日志库可以把返回值作为结构化字段写入 JSON 或适配到 OpenTelemetry Logs API。

package correlation

import (
    "context"

    "go.opentelemetry.io/otel/trace"
)

// FieldsFromContext 只读取当前 SpanContext，不在缺少上下文时伪造 ID。
func FieldsFromContext(ctx context.Context) map[string]string {
    sc := trace.SpanContextFromContext(ctx)
    if !sc.IsValid() {
        // 后台任务或系统日志可能没有 span，交给上层按 Resource 补充。
        return map[string]string{}
    }

    fields := map[string]string{
        // TraceID 用于跨服务聚合整条请求链路。
        "trace_id": sc.TraceID().String(),
        // SpanID 用于把日志缩小到当前处理阶段。
        "span_id": sc.SpanID().String(),
        // TraceFlags 保留采样等传播信息，便于解释为何查不到完整 trace。
        "trace_flags": sc.TraceFlags().String(),
    }
    return fields
}

这个函数的边界很重要：无效的 SpanContext 返回空字段，而不是写入一个看似合法的随机值。没有 trace 的系统日志、定时任务启动日志和进程崩溃前日志，应该通过 service.name、host.name、容器或进程信息来定位，不能为了字段齐全而伪造链路。

让每条 LogRecord 都有可查询的关联字段

OpenTelemetry Logs Data Model 把 TraceId、SpanId、TraceFlags、时间、严重级别、正文、Resource 和 Attributes 分开定义。落到 JSON 日志时，兼容规范建议把 trace_id、span_id 和 trace_flags 放在顶层，避免它们埋在无法统一检索的长文本里。

{
  "timestamp": "2026-11-11T14:00:00.120Z",
  "severity": "ERROR",
  "body": "inventory lookup failed",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "trace_flags": "01",
  "resource": {
    "service.name": "inventory-api",
    "service.version": "2026.11"
  },
  "attributes": {
    "rpc.method": "GetStock",
    "error.type": "timeout"
  }
}

上面的 JSON 是字段关系示例，不依赖某个日志后端。body 保存人和机器都能理解的事件内容，attributes 放可筛选的请求或错误属性，resource 描述产生这条 telemetry 的服务实例。检索时先用 trace_id 聚合，再用 span_id 缩小到具体阶段，最后根据属性判断是超时、重试还是业务拒绝。

让 Collector 的两条 pipeline 保留同一关联键

Logs 与 traces 可以在 Collector 中使用不同 receiver、processor 和 exporter，但分流不等于分离关联。只要 LogRecord 中的 TraceId 没有被处理器删除或改写，两个 pipeline 最终仍能在后端按同一 TraceId 交叉查询。

receivers:
  otlp:
    protocols:
      # gRPC 和 HTTP 只是接入协议，关联键来自 telemetry 内容本身。
      grpc:
      http:

processors:
  batch:
    # 批处理减少导出开销，但会增加少量可见延迟。
    timeout: 5s

exporters:
  otlphttp:
    # endpoint 由部署环境注入，示例不包含账号、Token 或真实地址。
    endpoint: https://observability.example.invalid/v1/otlp

service:
  pipelines:
    traces:
      # traces 与 logs 共用 receiver，仍由各自 pipeline 独立处理。
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    logs:
      # 日志保留 TraceId、SpanId 和 Resource 后再导出。
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

生产环境通常还会为 Logs 增加解析、脱敏、属性补充或采样策略。关键是不要把 trace_id 当成普通字符串在转换过程中丢弃，也不要用一个与 traces 不同的自定义字段名让后端无法识别。若必须兼容旧格式，按目标格式把 trace context 映射到明确的顶层字段，并在边界处保留原始语义。

没有 TraceContext 的日志怎样处理

并非每条日志都天然属于一条 trace。主机启动、容器调度、定时任务、批处理汇总和数据库自身日志可能没有请求上下文。对这些日志强行补 TraceId 会制造假关联，正确做法是使用 Resource context 和时间范围补足定位：至少保留 service.name、service.instance.id、主机或容器身份、环境和采集时间。

异步任务可以在“提交任务”与“执行任务”之间显式传递上下文，或者记录一个稳定的业务任务 ID，再把它作为 Attributes。业务 ID 解决的是任务级关联，TraceId 解决的是执行链路关联，两者可以同时存在，但不应互相冒充。

• 有有效 SpanContext：写入 TraceId、SpanId 和 TraceFlags。
• 只有服务实例信息：写入 Resource，不伪造 TraceId。
• 跨队列或跨批次：传递必要的上下文，并增加任务 ID、批次号等业务属性。
• 采集系统日志：优先补 Resource，按时间和来源定位，不声称它属于某条请求 trace。

关键取舍是完整性、成本和采样的一致性

把 Logs 与 traces 关联起来后，查询体验会变好，但代价也会变得明显。第一，日志字段变多，存储和索引成本会上升；第二，日志和 trace 的采样策略可能不同，出现“日志有 TraceId，但对应 trace 不完整”的情况；第三，Collector 的批处理和网络重试会让两类数据到达后端的时间不同。

因此不应把“能查到同一个 TraceId”理解成“所有 span 和所有日志都一定同时存在”。更实用的约定是：Logs 保留足够的 TraceId/SpanId 与 Resource，traces 记录采样状态；查询界面先显示关联关系，再明确提示当前数据是否经过采样或仍在导出队列中。

另一个取舍是字段标准化与业务细节的平衡。TraceId、SpanId、Resource 等字段应保持稳定，业务字段则控制数量和基数，避免把用户输入、完整 URL 或高基数字符串无限写入索引。关联字段用于找到正确链路，业务属性用于解释链路中的具体事件，职责不要混在一起。

上线后用四个信号判断关联是否可靠

关联方案部署后，可以从四个方向观察，而不是只统计日志条数：

1. 缺失率：有活动 span 的请求中，结构化日志缺少 TraceId 的比例是否持续升高。
2. 一致性：同一 TraceId 下的日志是否来自预期的服务，SpanId 是否能对应当前处理阶段。
3. 采样解释：日志中的 TraceFlags 与后端 trace 完整度是否匹配，避免把采样造成的缺口误判为断链。
4. 延迟差：Logs 和 traces 到达后端的时间差是否影响排障窗口，Collector 的批处理和重试是否需要调整。

如果缺失率集中在某一服务，先查该服务的日志适配层是否拿到了请求 context；如果跨服务都缺失，查传播头和 Collector 接收链路；如果只有系统日志缺失，则通常是它们本来就没有请求上下文，应回到 Resource 和任务 ID 的设计。

常见问题

只写 trace_id，不写 span_id 可以吗？

可以做粗粒度聚合，但排查一个 trace 内的多个阶段时不够。只要日志确实在某个 span 中产生，建议同时保存 TraceId 和 SpanId；OpenTelemetry 的数据模型也要求 SpanId 存在时通常应同时有 TraceId。

日志和 trace 在不同后端还能关联吗？

可以。关联的前提是两边都保留同一语义的 TraceId，并且查询层或跳转层知道如何用这个 ID 查询另一类数据。跨后端时还要额外处理字段大小写、十六进制格式和采样提示的一致性。

没有 trace 的日志要不要补一个 request_id？

不要为了填字段而伪造 TraceId。若它属于一个异步业务任务，可以增加任务 ID；若它是系统日志，则优先补 Resource 和观察时间，并把它明确标成无请求上下文的记录。

为什么同一 TraceId 下日志很多，但 trace 不完整？

常见原因是 traces 被采样、导出延迟或某个服务没有成功上报子 span。先看 TraceFlags 和采样策略，再查 Collector 的导出错误；不要仅凭日志数量判断 trace 一定完整。

总结来说，OpenTelemetry Logs 与 traces 的关联是一条数据契约：应用沿用当前 SpanContext，LogRecord 保留 TraceId、SpanId、TraceFlags 和 Resource，Collector 让 Logs 与 traces 独立处理但不破坏关联键，后端再按同一 TraceId 展开查询。这样设计后，日志不是孤立文本，而是请求链路中可定位、可解释的一部分。