可观测性与稳定性 / 系统课时
建立 Trace 与 Log 关联
建立 Trace 与 Log 关联
这篇解决分布式排障里最常见的断点:Trace 能看到慢在哪,Log 能看到发生了什么,但两者彼此找不到。核心做法不是在消息文本里手抄 ID,而是让日志在活动 Span 的上下文中生成,使 LogRecord 的 TraceId 与 SpanId 自动指向同一次执行。
学习目标
- 理解 TraceId、SpanId 与当前执行上下文如何进入 LogRecord
- 在 .NET 中验证同一日志与 Activity 具有一致的 TraceId、SpanId
- 能定位“日志有内容但没有追踪关联”的常见原因
关联的关键是活动上下文
Trace 与 Log 的关联依赖 LogRecord 顶层的 TraceId、SpanId 和可选 TraceFlags。TraceId 标识整条分布式调用链,SpanId 标识日志发生时所在的具体 Span。后端据此可以从一条日志跳到对应 Trace,也可以从一个 Span 查询同一执行上下文中的日志。
不要把这件事理解成“在日志文本后面拼两个字符串”。如果 ID 只存在于 Body 或普通 Attributes 中,采集器和后端未必会把它识别为标准追踪上下文字段。最稳妥的路径是:日志产生时有活动 Span,日志桥接层从当前 Context 读取追踪上下文,并填入 LogRecord 的标准字段。

用活动 Span 自动注入关联字段
下面用 .NET 演示最小可运行链路。.NET 的 OpenTelemetry 日志集成会在发出日志时读取当前 Activity;只要日志发生在活动上下文内,LogRecord 就会得到对应的 TraceId、SpanId 与 TraceFlags。
先创建项目并安装 Console Exporter:
dotnet new console -o trace-log-correlation
cd trace-log-correlation
dotnet add package OpenTelemetry.Exporter.Console预期结果:项目与依赖创建成功,命令退出码为 0;实际安装的稳定版本号可能不同。
将 Program.cs 替换为:
using System.Diagnostics;
using Microsoft.Extensions.Logging;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Trace;
const string sourceName = "Orders.Worker";
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder.AddOpenTelemetry(options =>
{
options.AddConsoleExporter();
});
});
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(sourceName)
.AddConsoleExporter()
.Build();
var logger = loggerFactory.CreateLogger("Orders.Worker");
using var activitySource = new ActivitySource(sourceName);
// Provider 已订阅该 ActivitySource,因此这里会创建可记录的 Activity。
using var activity = activitySource.StartActivity("ProcessOrder", ActivityKind.Internal)
?? throw new InvalidOperationException("Activity was not created.");
logger.LogInformation("Processing order {OrderId}", 42);运行:
dotnet run预期输出中,LogRecord 与 Activity 的两组 ID 应完全一致;实际 ID 与时间每次运行都会变化:
LogRecord.TraceId: <TRACE_ID>
LogRecord.SpanId: <SPAN_ID>
LogRecord.CategoryName: Orders.Worker
LogRecord.Body: Processing order {OrderId}
Activity.TraceId: <TRACE_ID>
Activity.SpanId: <SPAN_ID>
Activity.ActivitySourceName: Orders.Worker
Activity.DisplayName: ProcessOrder这里不需要手动把 Activity.Current.TraceId 拼进消息。日志桥接层读取当前活动上下文并写入标准字段,既避免业务代码重复,也减少“文本里有 ID、OTLP 字段却为空”的伪关联。
跨服务时保持 TraceId,更新 SpanId
一次请求经过多个服务时,传播的是 Trace Context,而不是把上游 Span 原样复制到下游。下游从 traceparent 等载体提取父上下文,再创建自己的本地 Span,所以同一调用链通常表现为“TraceId 相同,SpanId 不同”。
例如订单服务调用支付服务:订单服务日志携带 TraceId=T、SpanId=A;支付服务收到上下文后创建子 Span,支付日志携带 TraceId=T、SpanId=B。按 TraceId 搜索可以聚合整条链路的日志,按 SpanId 则能把日志定位到具体执行片段。
日志没有 TraceId 时按顺序排查
先确认日志发生时确实存在活动 Span。启动 Span 之前、结束 Span 之后,或者在不受追踪的后台线程中写日志,都可能得到空关联字段。对 .NET 可直接临时检查 Activity.Current 是否为空,但不要长期把它当作业务日志字段。
接着检查异步上下文有没有被截断。常规 async/await 会传播 .NET 的活动上下文,但显式抑制执行上下文、错误的线程切换封装或某些自定义队列消费方式可能让 Activity.Current 丢失。此时应该修复上下文传播,而不是在下游重新造一套 ID。
如果日志来自文件或 stdout,而不是进程内日志桥接,还要检查 Collector 是否把源日志里的 trace ID、span ID 解析成 LogRecord 的标准追踪字段。仅保留为 attributes.trace_id、attributes.span_id 不一定能触发后端的原生 Trace-Log 关联能力。
最后检查后端是否同时接收了 Trace 与 Log,并且支持按标准字段建立关联。日志中存在 TraceId 不代表对应 Trace 一定可查询:如果该 Trace 因采样策略没有被保存,日志仍可能带着 ID,但跳转目标不存在。
用双向跳转作为最终验收
最小验收不看“日志里是否打印了 32 位十六进制字符串”,而看关联是否真的可用。先触发一次请求或任务,找到对应 Trace,再从某个 Span 打开相关日志;随后从其中一条日志反向跳回 Trace,并确认 TraceId 一致、SpanId 指向预期 Span。
没有可观测后端时,可以先像上面的 Console Exporter 示例一样比较 LogRecord 与 Activity 的 ID,验证应用侧注入是否成立。接入后端后再做双向跳转验收,才能同时覆盖应用上下文、日志桥接、OTLP 传输、后端索引与采样策略这几层。只有这条链完整,Trace 与 Log 的关联才真正能用于线上定位。