Skip to content

NLog integration with Microsoft Activity TraceId and SpanId

License

Notifications You must be signed in to change notification settings

NLog/NLog.DiagnosticSource

Repository files navigation

NLog.DiagnosticSource

NLog ActivityTraceLayoutRenderer for Microsoft Activity Trace

NLog DiagnosticListenerTarget for Microsoft DiagnosticSource

Version AppVeyor

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>