Serilog.Sinks.OpenTelemetry
1.2.0-dev-00253
Prefix Reserved
See the version list below for details.
dotnet add package Serilog.Sinks.OpenTelemetry --version 1.2.0-dev-00253
NuGet\Install-Package Serilog.Sinks.OpenTelemetry -Version 1.2.0-dev-00253
<PackageReference Include="Serilog.Sinks.OpenTelemetry" Version="1.2.0-dev-00253" />
paket add Serilog.Sinks.OpenTelemetry --version 1.2.0-dev-00253
#r "nuget: Serilog.Sinks.OpenTelemetry, 1.2.0-dev-00253"
// Install Serilog.Sinks.OpenTelemetry as a Cake Addin #addin nuget:?package=Serilog.Sinks.OpenTelemetry&version=1.2.0-dev-00253&prerelease // Install Serilog.Sinks.OpenTelemetry as a Cake Tool #tool nuget:?package=Serilog.Sinks.OpenTelemetry&version=1.2.0-dev-00253&prerelease
Serilog.Sinks.OpenTelemetry
This Serilog sink transforms Serilog events into OpenTelemetry
LogRecord
s 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. The inline configuration looks like:
Log.Logger = new LoggerConfiguration()
.WriteTo.OpenTelemetry(
endpoint: "http://127.0.0.1:4318/v1/logs",
protocol: OtlpProtocol.HttpProtobuf)
.CreateLogger();
This configuration is appropriate only for simple, local logging setups.
More complicated use cases will need to use the options configuration, which looks like:
Log.Logger = new LoggerConfiguration()
.WriteTo.OpenTelemetry(options =>
{
options.Endpoint = "http://127.0.0.1:4318/v1/logs";
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 imporant parameters are discussed in the following
sections.
Endpoint and protocol
The default endpoint is http://localhost:4317
, which will send
logs to an OpenTelemetry collector running on the same machine over
the gRPC protocol. This is appropriate for testing or for using a
local OpenTelemetry collector as a proxy for a downstream logging service.
In most production scenarios, you will want to set an endpoint. To do so,
add the endpoint
argument to the WriteTo.OpenTelemetry()
call.
You may also want to set the protocol explicitly. 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.
When the OtlpProtocol.HttpProtobuf
option is specified, the endpoint
URL must include the full path, for example http://localhost:4318/v1/logs
.
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();
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.
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.
Copyright © Serilog Contributors - Provided under the Apache License, Version 2.0.
Product | Versions 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 was computed. 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 is compatible. |
.NET Framework | net461 was computed. net462 is compatible. net463 was computed. net47 was computed. net471 was computed. 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. |
-
.NETFramework 4.6.2
- Google.Protobuf (>= 3.23.4)
- Grpc.Net.Client (>= 2.55.0)
- Serilog (>= 3.1.0)
- Serilog.Sinks.PeriodicBatching (>= 3.1.0)
- System.Diagnostics.DiagnosticSource (>= 7.0.2)
-
.NETStandard 2.0
- Google.Protobuf (>= 3.23.4)
- Grpc.Net.Client (>= 2.55.0)
- Serilog (>= 3.1.0)
- Serilog.Sinks.PeriodicBatching (>= 3.1.0)
- System.Diagnostics.DiagnosticSource (>= 7.0.2)
-
.NETStandard 2.1
- Google.Protobuf (>= 3.23.4)
- Grpc.Net.Client (>= 2.55.0)
- Serilog (>= 3.1.0)
- Serilog.Sinks.PeriodicBatching (>= 3.1.0)
- System.Diagnostics.DiagnosticSource (>= 7.0.2)
-
net6.0
- Google.Protobuf (>= 3.23.4)
- Grpc.Net.Client (>= 2.55.0)
- Serilog (>= 3.1.0)
- Serilog.Sinks.PeriodicBatching (>= 3.1.0)
NuGet packages (29)
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 (8)
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 | 201,446 | 9/24/2024 |
4.1.1-dev-00356 | 73 | 9/24/2024 |
4.1.1-dev-00351 | 217 | 9/18/2024 |
4.1.0 | 174,558 | 9/5/2024 |
4.1.0-dev-00344 | 93 | 9/5/2024 |
4.1.0-dev-00336 | 2,370 | 8/20/2024 |
4.1.0-dev-00333 | 198 | 8/19/2024 |
4.0.0 | 305,594 | 7/28/2024 |
4.0.0-dev-00325 | 1,123 | 7/26/2024 |
4.0.0-dev-00322 | 422 | 7/23/2024 |
4.0.0-dev-00317 | 2,467 | 7/16/2024 |
4.0.0-dev-00315 | 1,089 | 7/12/2024 |
4.0.0-dev-00313 | 2,706 | 6/25/2024 |
3.0.1-dev-00309 | 217 | 6/25/2024 |
3.0.0 | 438,056 | 6/6/2024 |
3.0.0-dev-00300 | 112 | 6/6/2024 |
3.0.0-dev-00298 | 25,878 | 5/8/2024 |
2.0.0 | 256,587 | 5/7/2024 |
2.0.0-dev-00289 | 129 | 5/7/2024 |
2.0.0-dev-00284 | 137 | 5/7/2024 |
2.0.0-dev-00282 | 182,825 | 3/18/2024 |
2.0.0-dev-00270 | 21,989 | 1/4/2024 |
2.0.0-dev-00261 | 838 | 1/2/2024 |
2.0.0-dev-00259 | 2,305 | 12/7/2023 |
1.2.0 | 1,366,037 | 11/15/2023 |
1.2.0-dev-00255 | 394 | 11/15/2023 |
1.2.0-dev-00253 | 494 | 11/9/2023 |
1.2.0-dev-00247 | 6,348 | 10/11/2023 |
1.2.0-dev-00243 | 513 | 10/3/2023 |
1.1.0 | 341,398 | 9/28/2023 |
1.1.0-dev-00239 | 480 | 9/28/2023 |
1.1.0-dev-00236 | 873 | 9/18/2023 |
1.0.3-dev-00230 | 5,347 | 8/24/2023 |
1.0.2 | 321,136 | 7/11/2023 |
1.0.2-dev-00227 | 639 | 7/10/2023 |
1.0.1 | 44,375 | 7/7/2023 |
1.0.1-dev-00223 | 626 | 7/7/2023 |
1.0.1-dev-00222 | 616 | 7/7/2023 |
1.0.1-dev-00218 | 5,993 | 6/13/2023 |
1.0.0 | 232,763 | 6/1/2023 |
1.0.0-dev-00214 | 1,543 | 5/30/2023 |
1.0.0-dev-00212 | 1,329 | 5/29/2023 |
1.0.0-dev-00208 | 11,627 | 5/26/2023 |
1.0.0-dev-00204 | 7,258 | 5/18/2023 |
1.0.0-dev-00202 | 1,597 | 5/17/2023 |
1.0.0-dev-00200 | 633 | 5/17/2023 |
1.0.0-dev-00194 | 831 | 5/15/2023 |
1.0.0-dev-00192 | 611 | 5/15/2023 |
1.0.0-dev-00188 | 2,578 | 5/5/2023 |
1.0.0-dev-00182 | 86 | 5/5/2023 |
1.0.0-dev-00178 | 517 | 5/4/2023 |
1.0.0-dev-00175 | 1,171 | 5/3/2023 |
1.0.0-dev-00173 | 1,755 | 5/2/2023 |
1.0.0-dev-00166 | 2,133 | 5/1/2023 |
1.0.0-dev-00161 | 98 | 4/30/2023 |
1.0.0-dev-00152 | 142 | 4/29/2023 |
1.0.0-dev-00151 | 599 | 4/29/2023 |
1.0.0-dev-00148 | 96 | 4/29/2023 |
1.0.0-dev-00143 | 4,423 | 4/24/2023 |
1.0.0-dev-00142 | 93 | 4/24/2023 |
1.0.0-dev-00141 | 97 | 4/24/2023 |
1.0.0-dev-00129 | 604 | 4/19/2023 |
1.0.0-dev-00128 | 123 | 4/19/2023 |
1.0.0-dev-00121 | 620 | 4/14/2023 |
1.0.0-dev-00120 | 244 | 4/14/2023 |
1.0.0-dev-00117 | 293 | 4/12/2023 |
1.0.0-dev-00113 | 49,973 | 3/14/2023 |
1.0.0-dev-00098 | 39,901 | 2/12/2023 |
1.0.0-dev-00091 | 124 | 2/12/2023 |
1.0.0-dev-00080 | 126 | 2/10/2023 |
0.5.0-dev-00078 | 1,382 | 2/9/2023 |
0.4.0-dev-00073 | 24,133 | 2/3/2023 |
0.2.0-dev-00063 | 7,299 | 1/23/2023 |
0.2.0-dev-00059 | 218 | 1/10/2023 |
0.1.0-dev-00048 | 111 | 1/10/2023 |
0.0.4-dev-00039 | 45,588 | 1/9/2023 |
0.0.3-dev-00036 | 116 | 1/9/2023 |
0.0.2-dev-00027 | 126 | 1/7/2023 |
0.0.1-dev-00018 | 116 | 1/4/2023 |
0.0.1-dev-00015 | 114 | 1/3/2023 |
0.0.1-dev-00013 | 118 | 1/3/2023 |