Serilog.Sinks.OpenTelemetry 4.0.0

Serilog.Sinks.OpenTelemetry

此 Serilog 沉淀将 Serilog 事件转换为 OpenTelemetry 的 LogRecord，并将它们发送到 OTLP（gRPC 或 HTTP）端点。

沉淀旨在完全符合 OpenTelemetry 日志协议。它不依赖 OpenTelemetry SDK 或 .NET API。

OpenTelemetry 支持具有标量值、数组和映射的属性。Serilog 同样如此。因此，沉淀在 Serilog 属性和 OpenTelemetry 属性之间进行一对一映射。默认情况下，不对属性进行平坦化、重命名或其他修改。

入门

要使用 OpenTelemetry 沉淀，首先安装 NuGet 包

dotnet add package Serilog.Sinks.OpenTelemetry

然后使用 WriteTo.OpenTelemetry() 启用沉淀

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry()
    .CreateLogger();

使用 Log.Information(...) 和类似方法生成日志，将转换后的日志发送到本地 OpenTelemetry OTLP 端点。

更完整的配置将指定 Endpoint、Protocol 和其他参数，例如 ResourceAttributes，如下面的示例所示。

配置

此沉淀支持两种配置样式：内联和选项。内联配置适用于简单、本地日志设置，如下所示

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry(
        endpoint: "http://127.0.0.1:4318/v1/logs",
        protocol: OtlpProtocol.HttpProtobuf)
    .CreateLogger();

更复杂的使用案例需要使用选项样式配置，如下所示

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry(options =>
    {
        options.Endpoint = "http://127.0.0.1:4318/v1/logs";
        options.Protocol = OtlpProtocol.HttpProtobuf;
    })
    .CreateLogger();

这支持沉淀的完整配置选项集。请参阅 OpenTelemetrySinkOptions.cs 文件以获取完全的选项集。以下部分讨论了一些更重要的参数。

端点和协议

默认端点和协议是 https://127.0.0.1:4317 和 OtlpProtocol.Grpc。

在大多数生产场景中，您需要设置端点和协议以适应您的部署环境。为此，请向 WriteTo.OpenTelemetry() 调用添加 endpoint 参数。

您还可能想设置协议。支持的值包括

• OtlpProtocol.Grpc：通过 gRPC 连接发送 OpenTelemetry 日志的 protobuf 表示形式（默认）。
• OtlpProtocol.HttpProtobuf：通过 HTTP 连接发送 OpenTelemetry 日志的 protobuf 表示形式。

资源属性

OpenTelemetry 日志可能包含一个“资源”，该资源提供了与日志关联的实体（通常是服务或库）的元数据。这些可能包含“资源属性”，并为主配置文件中的所有日志发射。

这些资源属性可以在配置日志时作为 Dictionary<string, Object> 提供。OpenTelemetry 允 许具有丰富值的资源属性；然而，此实现 仅 支持原语值的资源属性。

⚠️ 具有非原语值的资源属性将被静默忽略。

以下示例显示了如何在配置日志时指定资源属性。

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry(options =>
    {
        options.Endpoint = "http://127.0.0.1:4317";
        options.ResourceAttributes = new Dictionary<string, object>
        {
            ["service.name"] = "test-logging-service",
            ["index"] = 10,
            ["flag"] = true,
            ["value"] = 3.14
        };
    })
    .CreateLogger();

环境变量覆盖

沉淀还识别 OpenTelemetry 文档中描述的 OTEL_OTLP_EXPORTER_* 环境变量选择集，并将覆盖程序配置在运行时存在的任何环境变量值。

要关闭此行为，请向 WriteTo.OpenTelemetry() 配置方法传递 ignoreEnvironment: true。

Serilog LogEvent 到 OpenTelemetry 日志记录映射

以下表格提供了 Serilog 日志事件和 OpenTelemetry 日志记录之间的映射。

配置包含的数据

此节点支持通过IncludedData枚举标志配置如何将常见OpenTelemetry字段从Serilog LogEvent和.NET Activity上下文填充

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry(options =>
    {
        options.Endpoint = "http://127.0.0.1:4317";
        options.IncludedData: IncludedData.MessageTemplate |
                              IncludedData.TraceId | IncludedData.SpanId;
    })
    .CreateLogger();

示例显示了默认值；也可以使用IncludedData.MessageTemplateMD5HashAttribute来添加消息模板的MD5哈希值。

通过节点发送跟踪

承载类型为DateTime的SpanStartTimestamp属性的Serilog LogEvents将被此节点识别为跨度，并使用适当的OpenTelemetry端点和架构发送。节点的识别属性与SerilogTracing发出的属性相匹配。

除了对日志条目的字段进行映射之外，表示跟踪跨度的事件还可以携带以下列出的特殊属性。

示例

在example/Example子目录中包含了一个将日志记录到本地OpenTelemetry收集器的示例应用程序。在该目录下的README中可以看到如何运行示例的说明。

版权所有 © Serilog 贡献者 - 根据Apache License, Version 2.0提供。