可观测性与稳定性 / 系统课时
采集应用日志为 OpenTelemetry LogRecord
采集应用日志为 OpenTelemetry LogRecord
这篇把“应用写了一条日志”落到 OpenTelemetry 的统一日志模型上:先分清 LogRecord、Severity、Resource 与 Scope 的职责,再用 .NET ILogger 日志桥接生成真实 LogRecord,最后给出选择直接 SDK、日志桥接或 Collector 文件采集时的判断标准。
学习目标
- 说清 LogRecord、Severity、Resource、Instrumentation Scope 与 Attributes 的边界
- 使用现有日志框架的桥接方式生成并查看 OpenTelemetry LogRecord
- 根据应用可改造程度选择 SDK、日志桥接或 Collector 采集路径
先认清 LogRecord 的数据层次
LogRecord 是“一次日志事件”的统一表示。Timestamp 表示事件发生时间,ObservedTimestamp 表示采集端看到它的时间;Body 承载消息或结构化主体,Attributes 放这一次事件特有的键值,SeverityText 与 SeverityNumber 表达原始级别和标准化严重程度。若日志产生时存在追踪上下文,记录还可以携带 TraceId、SpanId 与 TraceFlags。
Resource 回答“谁产生了遥测”,通常放 service.name、service.version、部署环境、主机或容器等相对稳定的信息;它不应该被每条日志重复当作业务字段。Instrumentation Scope 回答“哪个模块或日志器发出了这条遥测”,可对应库、模块、类或日志器名称。Attributes 则描述当前事件,例如 order.id、retry.count。
| 层次 | 适合放什么 | 典型变化频率 |
|---|---|---|
| Resource | 服务、实例、运行环境 | 一批记录内通常稳定 |
| Instrumentation Scope | 组件、库、Logger 名称 | 随发射组件变化 |
| LogRecord 顶层字段 | 时间、严重级别、Body、Trace 上下文 | 每条记录都可能变化 |
| Attributes | 当前事件的结构化上下文 | 每条记录都可能变化 |

选择 SDK、日志桥接还是文件采集
对于已经使用成熟日志库的应用,优先保留原来的日志 API,让 OpenTelemetry Provider、Appender 或 Handler 把日志事件桥接成 LogRecord。这样既不需要把业务代码全面改写成 OpenTelemetry Logs API,也能继续使用原日志库已有的格式化、级别控制和生态能力。
直接调用 Logs API 更适合 instrumentation library、结构化事件,或确实需要直接控制 LogRecord 发射的代码。它不是“比日志框架更高级”的替代品;如果团队已经依赖 ILogger、Logback、Log4j 等日志抽象,桥接通常更自然。
当应用难以改造,只能输出文件、stdout、syslog 等传统日志时,可以让 OpenTelemetry Collector 读取并解析,再映射为统一 LogRecord。代价是需要维护解析规则,且 TraceId、SpanId、Severity、时间戳等字段必须从源格式正确提取,否则后端只能得到普通文本或普通 Attributes。
用 .NET 日志桥接生成 LogRecord
下面用稳定的 .NET ILogger 集成演示桥接路径。先创建控制台项目并安装 Console Exporter;Console Exporter 只用于教学观察,生产环境通常改为 OTLP Exporter。
dotnet new console -o otel-logs-demo
cd otel-logs-demo
dotnet add package OpenTelemetry.Exporter.Console预期结果:项目创建成功,OpenTelemetry.Exporter.Console 被写入项目依赖,三条命令均以退出码 0 结束;实际恢复出的稳定版本号可能不同。
将 Program.cs 替换为下面内容。这里把 orders-worker 放进 Resource,把 Orders.Worker 作为 logger category;导出为 OTLP 时,该 category 会作为日志的 instrumentation scope 名称。
using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;
using OpenTelemetry.Resources;
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder.AddOpenTelemetry(options =>
{
// Resource 描述产生遥测的服务,而不是某一次业务事件。
options.SetResourceBuilder(
ResourceBuilder.CreateDefault()
.AddService("orders-worker", serviceVersion: "1.0.0"));
options.AddConsoleExporter();
});
});
var logger = loggerFactory.CreateLogger("Orders.Worker");
// 参数保持结构化,避免先插值成不可查询的整段字符串。
logger.LogInformation("Order {OrderId} accepted", 42);
logger.LogWarning("Order {OrderId} retry count is {RetryCount}", 42, 2);运行程序:
dotnet run预期输出会包含两条 LogRecord,时间等动态值每次不同;关键字段应类似:
LogRecord.Timestamp: <TIME>
LogRecord.CategoryName: Orders.Worker
LogRecord.Severity: Info
LogRecord.SeverityText: Information
LogRecord.Body: Order {OrderId} accepted
LogRecord.Attributes (Key:Value):
OrderId: 42
Resource associated with LogRecord:
service.name: orders-worker
service.version: 1.0.0第二条记录的严重级别应为 Warning,并包含 OrderId: 42 与 RetryCount: 2。控制台输出的排版可能随 SDK 版本略有变化,但 Resource、Severity、Body 与结构化属性的语义不应改变。
把字段放对位置再接生产出口
生产接入时,先固定 Resource:至少稳定设置 service.name,需要区分发布版本时再加 service.version,需要区分实例时再使用实例相关资源属性。不要把 order.id、user.id 这类高变化业务值塞进 Resource,它们应该留在 LogRecord Attributes。
Severity 也不要靠字符串颜色或消息前缀推断。桥接层应把源日志级别映射为 OpenTelemetry 的严重程度,同时保留原始 SeverityText。真正需要筛选“错误及以上”时,应使用标准化严重程度,而不是依赖 "ERROR"、"Error"、"err" 等不同字符串拼写。
最后把教学用 Console Exporter 换成 OTLP Exporter,送往 Collector 或后端。验收时至少检查四件事:服务名能按 Resource 过滤、logger/module 能按 Scope 区分、结构化参数没有被压平成整段字符串、不同日志级别能被正确查询。做到这四点,应用日志才算真正进入统一的 OpenTelemetry LogRecord 模型,而不是仅仅“换了一个输出终端”。