Add NLog instrumentation for OpenTelemetry .NET Auto-Instrumentation

.cspell/other.txt

@@ -41,6 +41,7 @@ mycompanymyproductmylibrary
 MYSQLCONNECTOR
 MYSQLDATA
 NETRUNTIME
+NLOG
 Npgsql
 NSERVICEBUS
 omnisharp

CHANGELOG.md

@@ -9,6 +9,9 @@ This component adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 
 ### Added
 
+- Support for [`NLog`](https://www.nuget.org/packages/NLog/)
+  logs instrumentation for versions `5.*` and `6.*` on .NET using duck typing
+  for zero-config auto-injection.
 - Support for .NET 10.
 - Experimental support for file-based configuration.
 - Experimental support for configuration based instrumentation.

OpenTelemetry.AutoInstrumentation.sln

@@ -247,6 +247,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SdkVersionAnalyzer", "tools
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TestApplication.Log4NetBridge", "test\test-applications\integrations\TestApplication.Log4NetBridge\TestApplication.Log4NetBridge.csproj", "{926B7C03-42C2-4192-94A7-CD0B1C693279}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TestApplication.NLogBridge", "test\test-applications\integrations\TestApplication.NLogBridge\TestApplication.NLogBridge.csproj", "{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TestApplication.SelectiveSampler", "test\test-applications\integrations\TestApplication.SelectiveSampler\TestApplication.SelectiveSampler.csproj", "{FD1A1ABD-6A48-4E94-B5F7-2081AFCD1BBB}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TestApplication.ProfilerSpanStoppageHandling", "test\test-applications\integrations\TestApplication.ProfilerSpanStoppageHandling\TestApplication.ProfilerSpanStoppageHandling.csproj", "{665280EB-F428-4C04-A293-33228C73BF8A}"
@@ -1539,6 +1541,22 @@ Global
 		{926B7C03-42C2-4192-94A7-CD0B1C693279}.Release|x64.Build.0 = Release|x64
 		{926B7C03-42C2-4192-94A7-CD0B1C693279}.Release|x86.ActiveCfg = Release|x86
 		{926B7C03-42C2-4192-94A7-CD0B1C693279}.Release|x86.Build.0 = Release|x86
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|Any CPU.ActiveCfg = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|Any CPU.Build.0 = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|ARM64.ActiveCfg = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|ARM64.Build.0 = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|x64.ActiveCfg = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|x64.Build.0 = Debug|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|x86.ActiveCfg = Debug|x86
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Debug|x86.Build.0 = Debug|x86
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|Any CPU.ActiveCfg = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|Any CPU.Build.0 = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|ARM64.ActiveCfg = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|ARM64.Build.0 = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|x64.ActiveCfg = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|x64.Build.0 = Release|x64
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|x86.ActiveCfg = Release|x86
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D}.Release|x86.Build.0 = Release|x86
 		{FD1A1ABD-6A48-4E94-B5F7-2081AFCD1BBB}.Debug|Any CPU.ActiveCfg = Debug|x64
 		{FD1A1ABD-6A48-4E94-B5F7-2081AFCD1BBB}.Debug|Any CPU.Build.0 = Debug|x64
 		{FD1A1ABD-6A48-4E94-B5F7-2081AFCD1BBB}.Debug|ARM64.ActiveCfg = Debug|x64
@@ -1693,6 +1711,7 @@ Global
 		{AA3E0C5C-A4E2-46AB-BD18-2D30D3ABF692} = {E409ADD3-9574-465C-AB09-4324D205CC7C}
 		{C75FA076-D460-414B-97F7-6F8D0E85AE74} = {00F4C92D-6652-4BD8-A334-B35D3E711BE6}
 		{926B7C03-42C2-4192-94A7-CD0B1C693279} = {E409ADD3-9574-465C-AB09-4324D205CC7C}
+		{A7B8C9D0-1E2F-3A4B-5C6D-7E8F9A0B1C2D} = {E409ADD3-9574-465C-AB09-4324D205CC7C}
 		{FD1A1ABD-6A48-4E94-B5F7-2081AFCD1BBB} = {E409ADD3-9574-465C-AB09-4324D205CC7C}
 		{665280EB-F428-4C04-A293-33228C73BF8A} = {E409ADD3-9574-465C-AB09-4324D205CC7C}
 		{500BF40F-EECB-4F6A-377B-EDBDFFDE09BE} = {E409ADD3-9574-465C-AB09-4324D205CC7C}

build/LibraryVersions.g.cs

@@ -68,6 +68,15 @@ public static partial class LibraryVersion
                 new("3.2.0"),
             ]
         },
+        {
+            "TestApplication.NLogBridge",
+            [
+                new("5.0.0"),
+                new("5.3.4"),
+                new("6.0.0"),
+                new("6.0.4"),
+            ]
+        },
         {
             "TestApplication.MassTransit",
             [

docs/config.md

@@ -202,10 +202,11 @@ due to lack of stable semantic convention.
 
 **Status**: [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md).
 
-| ID        | Instrumented library                                                                                                            | Supported versions | Instrumentation type     | Status                                                                                                                            |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------|--------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `ILOGGER` | [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging) **Not supported on .NET Framework** | ≥8.0.0             | bytecode or source \[1\] | [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) |
-| `LOG4NET` | [log4net](https://www.nuget.org/packages/log4net) \[2\]                                                                         | ≥2.0.13 && < 4.0.0 | bytecode                 | [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) |
+| ID        | Instrumented library                                                                                                            | Supported versions | Instrumentation type   | Status                                                                                                                            |
+|-----------|---------------------------------------------------------------------------------------------------------------------------------|--------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `ILOGGER` | [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging) **Not supported on .NET Framework** | ≥9.0.0             | bytecode or source \[1\] | [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) |
+| `LOG4NET` | [log4net](https://www.nuget.org/packages/log4net) \[2\]                                                                           | ≥2.0.13 && < 4.0.0 | bytecode               | [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) |
+| `NLOG`    | [NLog](https://www.nuget.org/packages/NLog) \[3\]                                                                                 | ≥5.0.0 && < 7.0.0  | bytecode               | [Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md) |
 
 \[1\]: For ASP.NET Core applications, the `LoggingBuilder` instrumentation
 can be enabled without using the .NET CLR Profiler by setting
@@ -215,6 +216,9 @@ the `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES` environment variable to
 \[2\]: Instrumentation provides both [trace context injection](./log-trace-correlation.md#log4net-trace-context-injection)
 and [logs bridge](./log4net-bridge.md).
 
+\[3\]:  Instrumentation provides both [trace context injection](./log-trace-correlation.md#log4net-trace-context-injection)
+and [logs bridge](./nlog-bridge.md).
+
 ### Instrumentation options
 
 | Environment variable                                                              | Description                                                                                                                                                                                                                              | Default value | Status                                                                                                                            |

docs/log-trace-correlation.md

@@ -61,3 +61,26 @@ Following properties are set by default on the collection of logging event's pro
 
 This allows for trace context to be logged into currently configured log destination,
  e.g. a file. In order to use them, pattern needs to be updated.
+
+### `NLog`
+
+See [`nlog-bridge`](./nlog-bridge.md).
+
+## `NLog` trace context injection
+
+> [!IMPORTANT]
+> NLog trace context injection is an experimental feature.
+
+The `NLog` trace context injection is enabled by default.
+It can be disabled by setting `OTEL_DOTNET_AUTO_LOGS_NLOG_INSTRUMENTATION_ENABLED` to `false`.
+
+Context injection is supported for `NLOG` in versions >= 5.0.0 && < 7.0.0
+
+Following properties are set by default on the collection of logging event's properties:
+
+- `trace_id`
+- `span_id`
+- `trace_flags`
+
+This allows for trace context to be logged into currently configured log destination,
+ e.g. a file. In order to use them, pattern needs to be updated.

docs/log4net-bridge.md

@@ -48,5 +48,3 @@ In order for the bridge to be added, at least 1 other appender has to be configu
 Bridge should not be used when appenders are configured for both root and component loggers.
 Enabling a bridge in such scenario would result in bridge being appended to both appender collections,
 and logs duplication. 
-
-

docs/nlog-bridge.md

@@ -0,0 +1,46 @@
+# `NLog` [logs bridge](https://opentelemetry.io/docs/specs/otel/glossary/#log-appender--bridge)
+
+> [!IMPORTANT]
+> NLog bridge is an experimental feature.
+
+The `NLog` logs bridge is disabled by default. In order to enable it,
+set `OTEL_DOTNET_AUTO_LOGS_ENABLE_NLOG_BRIDGE` to `true`.
+
+Bridge is supported for `NLOG` in versions >= 5.0.0 && < 7.0.0
+
+If `NLOG` is used as a [logging provider](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging-providers),
+`NLOG` bridge should not be enabled, in order to reduce possibility of
+duplicated logs export.
+
+## `NLog` logging events conversion
+
+`NLog`'s `ILoggingEvent`s are converted to OpenTelemetry log records in
+a following way:
+
+- `TimeStamp` is set as a `Timestamp`
+- `Level.Name` is set as a `SeverityText`
+- `FormattedMessage` is set as a `Body` if it is available
+- Otherwise, `Message` is set as a `Body`
+- `LoggerName` is set as an `InstrumentationScope.Name`
+- `GetProperties()`, apart from builtin properties prefixed with `nlog:`, `NLog.`,
+  are added as attributes
+- `Exception` is used to populate the following properties: `exception.type`,
+  `exception.message`, `exception.stacktrace`
+- `Level.Value` is mapped to `SeverityNumber` as outlined in the next section
+
+### `NLog` level severity mapping
+
+`NLog` levels are mapped to OpenTelemetry severity types according to
+ following rules based on their numerical values.
+
+Levels with numerical values of:
+
+- Equal to `LogLevel.Fatal` is mapped to `LogRecordSeverity.Fatal`
+- Equal to `LogLevel.Error` is mapped to `LogRecordSeverity.Error`
+- Equal to `LogLevel.Warn` is mapped to `LogRecordSeverity.Warn`
+- Equal to `LogLevel.Info` is mapped to `LogRecordSeverity.Info`
+- Equal to `LogLevel.Debug` is mapped to `LogRecordSeverity.Debug`
+- Equal to `LogLevel.Trace` is mapped to `LogRecordSeverity.Trace`
+- Equal to `LogLevel.Off` is mapped to `LogRecordSeverity.Trace`
+- Any other is mapped to `LogRecordSeverity.Info`.
+

src/OpenTelemetry.AutoInstrumentation/.publicApi/net462/PublicAPI.Unshipped.txt

@@ -1,3 +1,6 @@
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteLogEventToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsLegacyIntegration
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration0
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration1
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration2

src/OpenTelemetry.AutoInstrumentation/.publicApi/net8.0/PublicAPI.Unshipped.txt

@@ -1,3 +1,6 @@
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteLogEventToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsLegacyIntegration
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration0
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration1
 OpenTelemetry.AutoInstrumentation.Instrumentations.NoCode.NoCodeIntegration2

src/OpenTelemetry.AutoInstrumentation/Configurations/ConfigurationKeys.cs

@@ -240,6 +240,12 @@ public static class Logs
         /// </summary>
         public const string EnableLog4NetBridge = "OTEL_DOTNET_AUTO_LOGS_ENABLE_LOG4NET_BRIDGE";
 
+        /// <summary>
+        /// Configuration key for whether or not experimental NLog bridge
+        /// should be enabled.
+        /// </summary>
+        public const string EnableNLogBridge = "OTEL_DOTNET_AUTO_LOGS_ENABLE_NLOG_BRIDGE";
+
         /// <summary>
         /// Configuration key for disabling all log instrumentations.
         /// </summary>

src/OpenTelemetry.AutoInstrumentation/Configurations/LogInstrumentation.cs

@@ -17,4 +17,9 @@ internal enum LogInstrumentation
     /// Log4Net instrumentation.
     /// </summary>
     Log4Net = 1,
+
+    /// <summary>
+    /// NLog instrumentation.
+    /// </summary>
+    NLog = 2,
 }

src/OpenTelemetry.AutoInstrumentation/Configurations/LogSettings.cs

@@ -34,6 +34,11 @@ internal class LogSettings : Settings
     /// </summary>
     public bool EnableLog4NetBridge { get; private set; }
 
+    /// <summary>
+    /// Gets a value indicating whether the experimental NLog bridge is enabled.
+    /// </summary>
+    public bool EnableNLogBridge { get; private set; }
+
     /// <summary>
     /// Gets the list of enabled instrumentations.
     /// </summary>
@@ -60,6 +65,7 @@ protected override void OnLoadEnvVar(Configuration configuration)
 
         IncludeFormattedMessage = configuration.GetBool(ConfigurationKeys.Logs.IncludeFormattedMessage) ?? false;
         EnableLog4NetBridge = configuration.GetBool(ConfigurationKeys.Logs.EnableLog4NetBridge) ?? false;
+        EnableNLogBridge = configuration.GetBool(ConfigurationKeys.Logs.EnableNLogBridge) ?? false;
 
         var instrumentationEnabledByDefault =
             configuration.GetBool(ConfigurationKeys.Logs.LogsInstrumentationEnabled) ??

src/OpenTelemetry.AutoInstrumentation/Generated/net462/SourceGenerators/SourceGenerators.InstrumentationDefinitionsGenerator/InstrumentationDefinitions.g.cs

@@ -17,7 +17,7 @@ internal static partial class InstrumentationDefinitions
 {
     private static NativeCallTargetDefinition[] GetDefinitionsArray()
     {
-        var nativeCallTargetDefinitions = new List<NativeCallTargetDefinition>(36);
+        var nativeCallTargetDefinitions = new List<NativeCallTargetDefinition>(37);
         // Traces
         var tracerSettings = Instrumentation.TracerSettings.Value;
         if (tracerSettings.TracesEnabled)
@@ -101,6 +101,12 @@ private static NativeCallTargetDefinition[] GetDefinitionsArray()
                 nativeCallTargetDefinitions.Add(new("log4net", "log4net.Appender.AppenderCollection", "ToArray", ["log4net.Appender.IAppender[]"], 2, 0, 13, 3, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.Log4Net.Bridge.Integrations.AppenderCollectionIntegration"));
                 nativeCallTargetDefinitions.Add(new("log4net", "log4net.Util.AppenderAttachedImpl", "AppendLoopOnAppenders", ["System.Int32", "log4net.Core.LoggingEvent"], 2, 0, 13, 3, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.Log4Net.TraceContextInjection.Integrations.AppenderAttachedImplIntegration"));
             }
+
+            // NLog
+            if (logSettings.EnabledInstrumentations.Contains(LogInstrumentation.NLog))
+            {
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "Log", ["System.Void", "NLog.LogEventInfo"], 5, 0, 0, 6, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.Bridge.Integrations.LoggerIntegration"));
+            }
         }
 
         // Metrics

src/OpenTelemetry.AutoInstrumentation/Generated/net8.0/SourceGenerators/SourceGenerators.InstrumentationDefinitionsGenerator/InstrumentationDefinitions.g.cs

@@ -17,7 +17,7 @@ internal static partial class InstrumentationDefinitions
 {
     private static NativeCallTargetDefinition[] GetDefinitionsArray()
     {
-        var nativeCallTargetDefinitions = new List<NativeCallTargetDefinition>(39);
+        var nativeCallTargetDefinitions = new List<NativeCallTargetDefinition>(42);
         // Traces
         var tracerSettings = Instrumentation.TracerSettings.Value;
         if (tracerSettings.TracesEnabled)
@@ -104,6 +104,14 @@ private static NativeCallTargetDefinition[] GetDefinitionsArray()
             {
                 nativeCallTargetDefinitions.Add(new("Microsoft.Extensions.Logging", "Microsoft.Extensions.Logging.LoggingBuilder", ".ctor", ["System.Void", "Microsoft.Extensions.DependencyInjection.IServiceCollection"], 8, 0, 0, 10, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.Logger.LoggingBuilderIntegration"));
             }
+
+            // NLog
+            if (logSettings.EnabledInstrumentations.Contains(LogInstrumentation.NLog))
+            {
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteLogEventToTargets", ["System.Void", "NLog.LogEventInfo", "NLog.Internal.ITargetWithFilterChain"], 6, 0, 0, 6, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteLogEventToTargetsIntegration"));
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteToTargets", ["System.Void", "NLog.LogEventInfo", "NLog.Internal.ITargetWithFilterChain"], 5, 0, 0, 5, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsIntegration"));
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteToTargets", ["System.Void", "NLog.LogEventInfo", "NLog.Internal.TargetWithFilterChain"], 5, 0, 0, 5, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.WriteToTargetsLegacyIntegration"));
+            }
         }
 
         // Metrics

src/OpenTelemetry.AutoInstrumentation/Instrumentation.cs

@@ -358,7 +358,18 @@ private static void InitializeBufferProcessing(TimeSpan exportInterval, TimeSpan
     {
         // ILogger bridge is initialized using ILogger-specific extension methods in LoggerInitializer class.
         // That extension methods sets up its own LogProvider.
-        if (LogSettings.Value.EnableLog4NetBridge && LogSettings.Value.LogsEnabled && LogSettings.Value.EnabledInstrumentations.Contains(LogInstrumentation.Log4Net))
+
+        Logger.Debug($"InitializeLoggerProvider called. LogsEnabled={LogSettings.Value.LogsEnabled}, EnableLog4NetBridge={LogSettings.Value.EnableLog4NetBridge}, EnableNLogBridge={LogSettings.Value.EnableNLogBridge}");
+        Logger.Debug($"EnabledInstrumentations: {string.Join(", ", LogSettings.Value.EnabledInstrumentations)}");
+
+        // Initialize logger provider if any bridge is enabled
+        var shouldInitialize = LogSettings.Value.LogsEnabled && (
+            (LogSettings.Value.EnableLog4NetBridge && LogSettings.Value.EnabledInstrumentations.Contains(LogInstrumentation.Log4Net)) ||
+            (LogSettings.Value.EnableNLogBridge && LogSettings.Value.EnabledInstrumentations.Contains(LogInstrumentation.NLog)));
+
+        Logger.Debug($"ShouldInitialize logger provider: {shouldInitialize}");
+
+        if (shouldInitialize)
         {
             // TODO: Replace reflection usage when Logs Api is made public in non-rc builds.
             // Sdk.CreateLoggerProviderBuilder()