Add NLog instrumentation for OpenTelemetry .NET Auto-Instrumentation

.cspell/other.txt

@@ -29,6 +29,7 @@ ILOGGER
 inetsrv
 JIT
 LINQ
+longdate
 MASSTRANSIT
 metricsexporter
 mkdir
@@ -41,6 +42,7 @@ mycompanymyproductmylibrary
 MYSQLCONNECTOR
 MYSQLDATA
 NETRUNTIME
+NLOG
 Npgsql
 NSERVICEBUS
 omnisharp

CHANGELOG.md

@@ -11,6 +11,9 @@ This component adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 
 - Add `-NoReset` switch parameter to skip service restart in PowerShell
   registration functions.
+- 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.
 
 ### Changed
 

OpenTelemetry.AutoInstrumentation.sln

@@ -246,6 +246,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}"
@@ -1538,6 +1540,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
@@ -1692,6 +1710,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", additionalMetaData: new() { { "NLogExtensionsLogging", "5.0.0" } }),
+                new("5.3.4", additionalMetaData: new() { { "NLogExtensionsLogging", "5.3.15" } }),
+                new("6.0.0", additionalMetaData: new() { { "NLogExtensionsLogging", "6.0.0" } }),
+                new("6.0.6", additionalMetaData: new() { { "NLogExtensionsLogging", "6.1.0" } }),
+            ]
+        },
         {
             "TestApplication.MassTransit",
             [

build/TargetFramework.cs

@@ -19,7 +19,7 @@ public class TargetFramework : Enumeration
 
     // should be in version order
     public static readonly TargetFramework[] NetFramework = {
-        NET462, NET47, NET471, NET472, NET472
+        NET462, NET47, NET471, NET472
     };
 
     public static implicit operator string(TargetFramework framework)

docs/config.md

@@ -206,6 +206,7 @@ due to lack of stable semantic convention.
 |-----------|---------------------------------------------------------------------------------------------------------------------------------|--------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
 | `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) |
+| `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/file-based-configuration.md

@@ -526,6 +526,7 @@ instrumentation/development:
     logs:
       ilogger:             # Microsoft.Extensions.Logging
       log4net:             # Log4Net
+      nlog:                # NLog
 ```
 
 ## Instrumentation options
@@ -567,6 +568,10 @@ instrumentation/development:
         # Logs bridge is disabled by default
         # More info about log4net bridge can be found at https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/log4net-bridge.md
         bridge_enabled: true
+      nlog:
+        # Logs bridge is disabled by default
+        # More info about NLog bridge can be found at https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/nlog-bridge.md
+        bridge_enabled: true
 ```
 
 ## Instrumentation Additional Sources

docs/log-trace-correlation.md

@@ -62,3 +62,27 @@ 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/nlog-bridge.md

@@ -0,0 +1,45 @@
+# `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 +1,2 @@
-
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsWithWrapperTypeIntegration

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

@@ -0,0 +1,2 @@
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsIntegration
+OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsWithWrapperTypeIntegration

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/FileBasedConfiguration/DotNetLogs.cs

@@ -17,7 +17,13 @@ internal class DotNetLogs
     /// Gets or sets the Log4Net logs instrumentation configuration.
     /// </summary>
     [YamlMember(Alias = "log4net")]
-    public Log4NetBridgeEnabled? Log4Net { get; set; }
+    public LogBridgeEnabled? Log4Net { get; set; }
+
+    /// <summary>
+    /// Gets or sets the Log4Net logs instrumentation configuration.
+    /// </summary>
+    [YamlMember(Alias = "nlog")]
+    public LogBridgeEnabled? NLog { get; set; }
 
     /// <summary>
     /// Returns the list of enabled log instrumentations.
@@ -36,6 +42,11 @@ public IReadOnlyList<LogInstrumentation> GetEnabledInstrumentations()
             result.Add(LogInstrumentation.Log4Net);
         }
 
+        if (NLog != null)
+        {
+            result.Add(LogInstrumentation.NLog);
+        }
+
         return result;
     }
 }

src/OpenTelemetry.AutoInstrumentation/Configurations/FileBasedConfiguration/Log4NetBridgeEnabled.cs → src/OpenTelemetry.AutoInstrumentation/Configurations/FileBasedConfiguration/LogBridgeEnabled.cs

@@ -7,7 +7,7 @@
 namespace OpenTelemetry.AutoInstrumentation.Configurations.FileBasedConfiguration;
 
 [EmptyObjectOnEmptyYaml]
-internal class Log4NetBridgeEnabled
+internal class LogBridgeEnabled
 {
     /// <summary>
     /// Gets or sets a value indicating whether the Log4Net bridge is enabled.

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) ??
@@ -85,6 +91,11 @@ protected override void OnLoadFile(YamlConfiguration configuration)
         {
             EnableLog4NetBridge = logs?.Log4Net?.BridgeEnabled ?? false;
         }
+
+        if (EnabledInstrumentations.Contains(LogInstrumentation.NLog))
+        {
+            EnableNLogBridge = logs?.NLog?.BridgeEnabled ?? false;
+        }
     }
 
     private static List<LogExporter> ParseLogExporter(Configuration configuration)

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>(42);
         // Traces
         var tracerSettings = Instrumentation.TracerSettings.Value;
         if (tracerSettings.TracesEnabled)
@@ -101,6 +101,17 @@ 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", "WriteToTargets", ["System.Void", "NLog.LogEventInfo", "NLog.Internal.ITargetWithFilterChain"], 5, 0, 0, 5, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsIntegration"));
+                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.NLogWriteToTargetsIntegration"));
+                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.NLogWriteToTargetsIntegration"));
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteToTargets", ["System.Void", "System.Type", "NLog.LogEventInfo", "NLog.Internal.ITargetWithFilterChain"], 5, 0, 0, 5, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsWithWrapperTypeIntegration"));
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteToTargets", ["System.Void", "System.Type", "NLog.LogEventInfo", "NLog.Internal.TargetWithFilterChain"], 5, 0, 0, 5, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsWithWrapperTypeIntegration"));
+                nativeCallTargetDefinitions.Add(new("NLog", "NLog.Logger", "WriteLogEventToTargets", ["System.Void", "System.Type", "NLog.LogEventInfo", "NLog.Internal.ITargetWithFilterChain"], 6, 0, 0, 6, 65535, 65535, AssemblyFullName, "OpenTelemetry.AutoInstrumentation.Instrumentations.NLog.TraceContextInjection.Integrations.NLogWriteToTargetsWithWrapperTypeIntegration"));
+            }
         }
 
         // Metrics