Serilog.Sinks.OpenTelemetry 4.1.1

Prefix Reserved
dotnet add package Serilog.Sinks.OpenTelemetry --version 4.1.1                
NuGet\Install-Package Serilog.Sinks.OpenTelemetry -Version 4.1.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Serilog.Sinks.OpenTelemetry" Version="4.1.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Sinks.OpenTelemetry --version 4.1.1                
#r "nuget: Serilog.Sinks.OpenTelemetry, 4.1.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Sinks.OpenTelemetry as a Cake Addin
#addin nuget:?package=Serilog.Sinks.OpenTelemetry&version=4.1.1

// Install Serilog.Sinks.OpenTelemetry as a Cake Tool
#tool nuget:?package=Serilog.Sinks.OpenTelemetry&version=4.1.1                

Serilog.Sinks.OpenTelemetry Build status NuGet Version

This Serilog sink transforms Serilog events into OpenTelemetry LogRecords and sends them to an OTLP (gRPC or HTTP) endpoint.

The sink aims for full compliance with the OpenTelemetry Logs protocol. It does not depend on the OpenTelemetry SDK or .NET API.

OpenTelemetry supports attributes with scalar values, arrays, and maps. Serilog does as well. Consequently, the sink does a one-to-one mapping between Serilog properties and OpenTelemetry attributes. There is no flattening, renaming, or other modifications done to the properties by default.

Getting started

To use the OpenTelemetry sink, first install the NuGet package:

dotnet add package Serilog.Sinks.OpenTelemetry

Then enable the sink using WriteTo.OpenTelemetry():

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

Generate logs using the Log.Information(...) and similar methods to send transformed logs to a local OpenTelemetry OTLP endpoint.

A more complete configuration would specify Endpoint, Protocol, and other parameters, such asResourceAttributes, as shown in the examples below.

Configuration

This sink supports two configuration styles: inline and options. Inline configuration is appropriate for simple, local logging setups, and looks like:

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

More complicated use cases need to use options-style configuration, which looks like:

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

This supports the sink's full set of configuration options. See the OpenTelemetrySinkOptions.cs file for the full set of options. Some of the more important parameters are discussed in the following sections.

Endpoint and protocol

The default endpoint and protocol are http://localhost:4317 and OtlpProtocol.Grpc.

In most production scenarios, you'll need to set an endpoint and protocol to suit your deployment environment. To do so, add the endpoint argument to the WriteTo.OpenTelemetry() call.

You may also want to set the protocol. The supported values are:

  • OtlpProtocol.Grpc: Sends a protobuf representation of the OpenTelemetry Logs over a gRPC connection (the default).
  • OtlpProtocol.HttpProtobuf: Sends a protobuf representation of the OpenTelemetry Logs over an HTTP connection.

Resource attributes

OpenTelemetry logs may contain a "resource" that provides metadata concerning the entity associated with the logs, typically a service or library. These may contain "resource attributes" and are emitted for all logs flowing through the configured logger.

These resource attributes may be provided as a Dictionary<string, Object> when configuring a logger. OpenTelemetry allows resource attributes with rich values; however, this implementation only supports resource attributes with primitive values.

⚠️ Resource attributes with non-primitive values will be silently ignored.

This example shows how the resource attributes can be specified when the logger is configured.

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

Environment variable overrides

The sink also recognizes a selection of the OTEL_OTLP_EXPORTER_* environment variables described in the OpenTelemetry documentation, and will override programmatic configuration with any environment variable values present at runtime.

To switch off this behavior, pass ignoreEnvironment: true to the WriteTo.OpenTelemetry() configuration methods.

Serilog LogEvent to OpenTelemetry log record mapping

The following table provides the mapping between the Serilog log events and the OpenTelemetry log records.

Serilog LogEvent OpenTelemetry LogRecord Comments
Exception.GetType().ToString() Attributes["exception.type"]
Exception.Message Attributes["exception.message"] Ignored if empty
Exception.StackTrace Attributes[ "exception.stacktrace"] Value of ex.ToString()
Level SeverityNumber Serilog levels are mapped to corresponding OpenTelemetry severities
Level.ToString() SeverityText
Message Body Culture-specific formatting can be provided via sink configuration
MessageTemplate Attributes[ "message_template.text"] Requires IncludedData. MessageTemplateText (enabled by default)
MessageTemplate (MD5) Attributes[ "message_template.hash.md5"] Requires IncludedData. MessageTemplateMD5 HashAttribute
Properties Attributes Each property is mapped to an attribute keeping the name; the value's structure is maintained
SpanId (Activity.Current) SpanId Requires IncludedData.SpanId (enabled by default)
Timestamp TimeUnixNano .NET provides 100-nanosecond precision
TraceId (Activity.Current) TraceId Requires IncludedData.TraceId (enabled by default)

Configuring included data

This sink supports configuration of how common OpenTelemetry fields are populated from the Serilog LogEvent and .NET Activity context via the IncludedData flags enum:

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

The example shows the default value; IncludedData.MessageTemplateMD5HashAttribute can also be used to add the MD5 hash of the message template.

Sending traces through the sink

Serilog LogEvents that carry a SpanStartTimestamp property of type DateTime will be recognized as spans by this sink, and sent using the appropriate OpenTelemetry endpoint and schema. The properties recognized by the sink match the ones emitted by SerilogTracing.

In addition to the field mapping performed for log records, events that represent trace spans can carry the special properties listed below.

Serilog LogEvent OpenTelemetry Span Comments
MessageTemplate Name
Properties["ParentSpanId"] ParentSpanId Value must be of type ActivitySpanId
Properties["SpanKind"] Kind Value must be of type ActivityKind
Properties["SpanStartTimestamp"] StartTimeUnixNano Value must be of type DateTime; .NET provides 100-nanosecond precision
Timestamp EndTimeUnixNano .NET provides 100-nanosecond precision

Suppressing other instrumentation

If the sink is used in an application that also instruments HTTP or gRPC requests using the OpenTelemetry libraries, this can be suppressed for outbound requests made by the sink using OnBeginSuppressInstrumentation:

Log.Logger = new LoggerConfiguration()
    .WriteTo.OpenTelemetry(options =>
    {
        options.OnBeginSuppressInstrumentation =
            OpenTelemetry.SuppressInstrumentationScope.Begin;
        // ...

Example

The example/Example subdirectory contains an example application that logs to a local OpenTelemetry collector. See the README in that directory for instructions on how to run the example.

.NET Framework Activity Traces

In .NET 5 and later versions, the Activity.DefaultIdFormat is ActivityIdFormat.W3C. In previous versions, the default format is ActivityIdFormat.Hierarchical. To make use of the Activity's traces and spans, you should set the global Activity.DefaultIdFormat to ActivityIdFormat.W3C in .NET Framework environments. Read more: Default ActivityIdFormat is W3C

Copyright © Serilog Contributors - Provided under the Apache License, Version 2.0.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 is compatible.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (28)

Showing the top 5 NuGet packages that depend on Serilog.Sinks.OpenTelemetry:

Package Downloads
SerilogTracing.Sinks.OpenTelemetry

Sends log events and traces to OTLP (gRPC or HTTP) endpoints. This package is obsolete; use Serilog.Sinks.OpenTelemetry v4.x or later instead.

Relativity.Transfer.SDK

Relativity Transfer SDK allows performing high-throughput transfers of files from and to Relativity environment.

PegasusLoggingService

Package Description

Newguys.Telemetry

Package Description

Fluxera.Extensions.Hosting.Modules.Serilog

A module that enables Serilog logging.

GitHub repositories (7)

Showing the top 5 popular GitHub repositories that depend on Serilog.Sinks.OpenTelemetry:

Repository Stars
fullstackhero/dotnet-starter-kit
Production Grade Cloud-Ready .NET 8 Starter Kit (Web API + Blazor Client) with Multitenancy Support, and Clean/Modular Architecture that saves roughly 200+ Development Hours! All Batteries Included.
SciSharp/BotSharp
The AI Agent Framework in .NET
featbit/featbit
A feature flags service written in .NET
abpframework/abp-samples
Sample solutions built with the ABP Framework
mehdihadeli/food-delivery-microservices
🍔 A practical and imaginary food delivery microservices, built with .Net 8, MassTransit, Domain-Driven Design, CQRS, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.
Version Downloads Last updated
4.1.1 50,107 9/24/2024
4.1.1-dev-00356 65 9/24/2024
4.1.1-dev-00351 214 9/18/2024
4.1.0 121,438 9/5/2024
4.1.0-dev-00344 88 9/5/2024
4.1.0-dev-00336 1,899 8/20/2024
4.1.0-dev-00333 137 8/19/2024
4.0.0 233,213 7/28/2024
4.0.0-dev-00325 889 7/26/2024
4.0.0-dev-00322 415 7/23/2024
4.0.0-dev-00317 2,218 7/16/2024
4.0.0-dev-00315 869 7/12/2024
4.0.0-dev-00313 2,357 6/25/2024
3.0.1-dev-00309 212 6/25/2024
3.0.0 376,104 6/6/2024
3.0.0-dev-00300 112 6/6/2024
3.0.0-dev-00298 22,630 5/8/2024
2.0.0 230,887 5/7/2024
2.0.0-dev-00289 128 5/7/2024
2.0.0-dev-00284 134 5/7/2024
2.0.0-dev-00282 170,009 3/18/2024
2.0.0-dev-00270 20,717 1/4/2024
2.0.0-dev-00261 837 1/2/2024
2.0.0-dev-00259 2,206 12/7/2023
1.2.0 1,267,463 11/15/2023
1.2.0-dev-00255 393 11/15/2023
1.2.0-dev-00253 493 11/9/2023
1.2.0-dev-00247 6,324 10/11/2023
1.2.0-dev-00243 513 10/3/2023
1.1.0 316,798 9/28/2023
1.1.0-dev-00239 477 9/28/2023
1.1.0-dev-00236 872 9/18/2023
1.0.3-dev-00230 5,186 8/24/2023
1.0.2 304,861 7/11/2023
1.0.2-dev-00227 637 7/10/2023
1.0.1 43,054 7/7/2023
1.0.1-dev-00223 625 7/7/2023
1.0.1-dev-00222 612 7/7/2023
1.0.1-dev-00218 5,819 6/13/2023
1.0.0 219,691 6/1/2023
1.0.0-dev-00214 1,542 5/30/2023
1.0.0-dev-00212 1,256 5/29/2023
1.0.0-dev-00208 10,314 5/26/2023
1.0.0-dev-00204 7,247 5/18/2023
1.0.0-dev-00202 1,596 5/17/2023
1.0.0-dev-00200 632 5/17/2023
1.0.0-dev-00194 829 5/15/2023
1.0.0-dev-00192 609 5/15/2023
1.0.0-dev-00188 2,519 5/5/2023
1.0.0-dev-00182 84 5/5/2023
1.0.0-dev-00178 515 5/4/2023
1.0.0-dev-00175 1,170 5/3/2023
1.0.0-dev-00173 1,753 5/2/2023
1.0.0-dev-00166 2,131 5/1/2023
1.0.0-dev-00161 96 4/30/2023
1.0.0-dev-00152 137 4/29/2023
1.0.0-dev-00151 500 4/29/2023
1.0.0-dev-00148 94 4/29/2023
1.0.0-dev-00143 4,321 4/24/2023
1.0.0-dev-00142 92 4/24/2023
1.0.0-dev-00141 96 4/24/2023
1.0.0-dev-00129 603 4/19/2023
1.0.0-dev-00128 120 4/19/2023
1.0.0-dev-00121 619 4/14/2023
1.0.0-dev-00120 243 4/14/2023
1.0.0-dev-00117 258 4/12/2023
1.0.0-dev-00113 49,123 3/14/2023
1.0.0-dev-00098 37,976 2/12/2023
1.0.0-dev-00091 123 2/12/2023
1.0.0-dev-00080 125 2/10/2023
0.5.0-dev-00078 1,378 2/9/2023
0.4.0-dev-00073 24,104 2/3/2023
0.2.0-dev-00063 7,295 1/23/2023
0.2.0-dev-00059 216 1/10/2023
0.1.0-dev-00048 110 1/10/2023
0.0.4-dev-00039 41,990 1/9/2023
0.0.3-dev-00036 115 1/9/2023
0.0.2-dev-00027 121 1/7/2023
0.0.1-dev-00018 116 1/4/2023
0.0.1-dev-00015 113 1/3/2023
0.0.1-dev-00013 115 1/3/2023