NLog.DiagnosticSource v5.2.1 — nugetz
304NotModified/NLog.DiagnosticSourcev5.2.1
✓ Verified.NET FW4.6.2.NET 6.0.NET 8.0.NET 10.0
NLog Integration for Microsoft System.Diagnostics.DiagnosticSource and Activity TraceId / SpanId
Get Started
$ dotnet add package NLog.DiagnosticSourceReadme
NLog.DiagnosticSource
NLog ActivityTraceLayoutRenderer for Microsoft Activity Trace
NLog DiagnosticListenerTarget for Microsoft DiagnosticSource
How to install
-
Install the package
Install-Package NLog.DiagnosticSource or in your csproj:
<PackageReference Include="NLog.DiagnosticSource" Version="5.*" />
-
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>
- 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
- 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
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>