可观测性与稳定性 / 系统课时

采集应用日志为 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 当前事件的结构化上下文 每条记录都可能变化

应用日志映射为 OpenTelemetry LogRecord 的层次与管线

选择 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。

bash
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 名称。

csharp
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);

运行程序:

bash
dotnet run

预期输出会包含两条 LogRecord,时间等动态值每次不同;关键字段应类似:

text
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 模型,而不是仅仅“换了一个输出终端”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

采集应用日志为 OpenTelemetry LogRecord

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通