https://github.com/nlog/nlog.diagnosticsource

NLog integration with Microsoft Activity TraceId and SpanId
https://github.com/nlog/nlog.diagnosticsource

csharp dotnet nlog nlog-target open-telemetry open-telemetry-csharp opentelemetry

Last synced: about 1 month ago
JSON representation

NLog integration with Microsoft Activity TraceId and SpanId

• Host: GitHub
• URL: https://github.com/nlog/nlog.diagnosticsource
• Owner: NLog
• License: bsd-3-clause
• Created: 2019-12-29T22:52:21.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-05-28T16:49:28.000Z (12 months ago)
• Last Synced: 2024-10-14T08:21:47.135Z (7 months ago)
• Topics: csharp, dotnet, nlog, nlog-target, open-telemetry, open-telemetry-csharp, opentelemetry
• Language: C#
• Homepage:
• Size: 127 KB
• Stars: 11
• Watchers: 4
• Forks: 3
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# NLog.DiagnosticSource

NLog ActivityTraceLayoutRenderer for [Microsoft Activity Trace](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md)

NLog DiagnosticListenerTarget for [Microsoft DiagnosticSource](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md)

[![Version](https://badge.fury.io/nu/NLog.DiagnosticSource.svg)](https://www.nuget.org/packages/NLog.DiagnosticSource)

[![AppVeyor](https://img.shields.io/appveyor/ci/nlog/NLog-DiagnosticSource/master.svg)](https://ci.appveyor.com/project/nlog/NLog-DiagnosticSource/branch/master)

### How to install

1) Install the package

    `Install-Package NLog.DiagnosticSource` or in your csproj:

    ```xml

    

    ```

2) Add to your nlog.config:

    ```xml

    

        

    

    ```

   Alternative register from code using fluent configuration API:

   ```csharp

   LogManager.Setup().SetupExtensions(ext => {

      ext.RegisterTarget();

      ext.RegisterLayoutRenderer();

   });

   ```

### 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}`:

```xml

    

    

    

```

**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](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loggerfactoryoptions.activitytrackingoptions):

```c#

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:

```xml

    

    

    

```