README.md

NLog.DiagnosticSource

NLog ActivityTraceLayoutRenderer for Microsoft Activity Trace

NLog DiagnosticListenerTarget for Microsoft DiagnosticSource

How to install

1. Install the package

   Install-Package NLog.DiagnosticSource or in your csproj:

   <PackageReference Include="NLog.DiagnosticSource" Version="5.*" />

2. Add to your nlog.config:

   <extensions>
       <add assembly="NLog.DiagnosticSource"/>
   </extensions>

   Alternative register from code using fluent configuration API:

   LogManager.Setup().SetupExtensions(ext => {
      ext.RegisterTarget<NLog.Targets.DiagnosticListenerTarget>();
      ext.RegisterLayoutRenderer<NLog.LayoutRenderers.ActivityTraceLayoutRenderer>();
   });

How to use ActivityTraceLayoutRenderer

The System.Diagnostics.Activity.Current from Microsoft allows one to create OpenTelemetry spans.

Example of NLog.config file that outputs span-details together with LogEvent by using ${activity}:

<nlog>
<extensions>
    <add assembly="NLog.DiagnosticSource"/>
</extensions>
<targets>
    <target name="console" xsi:type="console" layout="${message}|ActivityId=${activity:property=TraceId}" />
</targets>
<rules>
    <logger minLevel="Info" writeTo="console" />
</rules>
</nlog>

Property Enum Values

• Id : Hierarchical structure identifier that is concatenation of ParentIds
• SpanId : Identifier for the current activity (Ex. database activity within current request)
• ParentId : Identifier for the parent activity
• TraceId : Identifier for the root activity (Request Trace Identifier)
• OperationName : Operation name of the current activity
• DisplayName : Explicit assigned Activity DisplayName (with fallback to OperationName)
• StartTimeUtc : Time when the operation started
• Duration : Duration of the operation (formatted as TimeSpan)
• DurationMs : Duration of the operation (formatted as TimeSpan.TotalMilliseconds)
• Baggage : Collection of key/value pairs that are passed to children of this Activity (Use Format="@" for json-dictionary)
• Tags : Collection of key/value pairs that are NOT passed to children of this Activity (Use Format="@" for json-dictionary)
• CustomProperty : Custom property assigned to this activity. Must be used together with Item-option
• Events : Events attached to this activity (Use Format="@" for json-array)
• TraceState : W3C tracestate header
• TraceFlags : See System.Diagnostics.ActivityTraceFlags for activity (defined by the W3C ID specification). Can be combined with format="d"
• SourceName : Name of the activity source associated with this activity
• SourceVersion : Version of the activity source associated with this activity
• ActivityKind : Relationship kind between the activity, its parents, and its children. Can be combined with format="d"
• TraceStateString : W3C 'tracestate' header as a string

Formatting

• Format: Format for rendering the property.
• Culture: CultureInfo for rendering the property (Default Invariant Culture)
• Item: Lookup a single item from property-collection (Baggage, Tags, CustomProperty)
  • ${activity:property=Baggage:item=BaggageKey}
  • ${activity:property=Tags:item=TagKey}
  • ${activity:property=CustomProperty:item=PropertyKey}

Extract property values from parent or root

It is possible to specify that the above property should be extracted from either root- or parent-activity.

${activity:property=OperationName:parent=true}

${activity:property=OperationName:root=true}

Manually configure ActivityTrackingOptions

When using the default HostBuilder then it will automatically setup the following ActivityTrackingOptions:

builder.ConfigureLogging((hostingContext, loggingBuilder) =>
{
      loggingBuilder.Configure(options =>
      {
            options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                            | ActivityTrackingOptions.TraceId
                                            | ActivityTrackingOptions.ParentId;
      });
}).

If creating a custom HostBuilder, then one have to manually setup the ActivityTrackingOptions like shown above.

How to use DiagnosticListenerTarget

Example of NLog.config file that uses the diagnosticListener target:

<nlog>
<extensions>
    <add assembly="NLog.DiagnosticSource"/>
</extensions>
<targets>
    <target name="diagSource" xsi:type="diagnosticListener" layout="${message}" sourceName="nlog" eventName="${logger}" />
</targets>
<rules>
    <logger minLevel="Info" writeTo="diagSource" />
</rules>
</nlog>