This repo is no longer maintained. All of its functionality is now present in NServiceBus OTel support.

NServiceBus.Extensions.Diagnostics

Usage

The NServiceBus.Extensions.Diagnostics package extends NServiceBus to expose telemetry information via System.Diagnostics.

To use NServiceBus.Extensions.Diagnostics, simply reference the package. The DiagnosticsFeature is enabled by default.

The Diagnostics package exposes four different events from behaviors via Diagnostics:

• IIncomingPhysicalMessageContext
• IIncomingLogicalMessageContext
• IInvokeHandlerContext
• IOutgoingLogicalMessageContext
• IOutgoingPhysicalMessageContext

The Physical message variants include full Activity support. All diagnostics events pass through the corresponding context object as its event argument.

This package supports NServiceBus version 7.0 and above.

W3C traceparent and Correlation-Context support

The Diagnostics package also provides support for both the W3C Trace Context recommendation and W3C Correlation Context June 2020 draft.

The Trace Context supports propagates the traceparent and tracecontext headers into outgoing messages, and populates Activity parent ID based on incoming messages.

The Correlation Context support consumes incoming headers into Activity.Baggage, and propagates Activity.Baggage into outgoing messages.

If you would like to add additional correlation context, inside your handler you can add additional baggage:

Activity.Current.AddBaggage("mykey", "myvalue");

Correlation context can then flow out to tracing and observability tools. Common usage for correlation context are user IDs, session IDs, conversation IDs, and anything you might want to search traces to triangulate specific traces.

ActivitySource support

This package exposes an ActivitySource with a Name the same as the assembly, NServiceBus.Extensions.Diagnostics. Use this name in any ActivityListener-based listeners, including OpenTelemetry using the OpenTelemetry.Extensions.Hosting package:

services.AddOpenTelemetryTracing(builder => builder
    .AddSource("NServiceBus.Extensions.Diagnostics")

All the available OpenTelemetry semantic tags are set.

Configuring

In order to limit potentially sensitive information, the message contents are not passed through to the ActivitySource by default. To enable this, configure the InstrumentationOptions setting in your EndpointConfiguration:

var settings = endpointConfiguration.GetSettings();

settings.Set(new NServiceBus.Extensions.Diagnostics.InstrumentationOptions
{
    CaptureMessageBody = true
});

This will set a messaging.message_payload tag with the UTF8-decoded message body.

Enriching Activities

To enrich an Activity in a behavior or handler, the current executing NServiceBus activity is set in a ICurrentActivity extension value. In a handler or behavior you may retrieve this value and modify the Activity:

public Task Handle(Message message, IMessageHandlerContext context)
{
    var currentActivity = context.Extensions.Get<ICurrentActivity>();

    currentActivity.Current?.AddBaggage("cart.operation.id", message.Id.ToString());

    // rest of method
}

Metrics Usage

This package also optionally supports bridging NServiceBus.Metrics to System.Diagnostics.Metrics.

It exposes the existing NServiceBus metrics with a Meter named NServiceBus.Extensions.Diagnostics and corresponding Counter and Histogram instruments, using OpenTelemetry metrics instrument and attribute semantic conventions:

NServiceBus Probe Name	Instrument Name	Instrumentation Type
# of msgs successfully processed / sec	messaging.successes	Counter<long>
# of msgs pulled from the input queue /sec	messaging.fetches	Counter<long>
# of msgs failures / sec	messaging.failures	Counter<long>
Critical Time	messaging.client_server.duration	Histogram<double>
Processing Time	messaging.server.duration	Histogram<double>
Retries	messaging.retries	Counter<long>

Enable this feature, which also enables the NServiceBus.Metrics feature, in your endpoint configuration:

endpointConfiguration.EnableFeature<DiagnosticsMetricsFeature>();