Azure Service Bus

For the full compatibility matrix including supported installation methods, see Messaging systems.

This page assumes the core agent is already set up. If not, see Set up the APM .NET agent first.

Add the Elastic.Apm.Azure.ServiceBus NuGet package to your project:

dotnet add package Elastic.Apm.Azure.ServiceBus
		

Subscribe the appropriate diagnostics subscriber with the agent. Call this in your application startup, before any Service Bus operations occur:

If using Elastic.Apm.NetCoreAll: The subscribers are registered automatically — no further action is required.

If using Azure.Messaging.ServiceBus (current SDK):

Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());
		

If using Microsoft.Azure.ServiceBus (legacy, deprecated):

Agent.Subscribe(new MicrosoftAzureServiceBusDiagnosticsSubscriber());
		

For ASP.NET Core applications, call Agent.Subscribe() in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());

var app = builder.Build();
app.Run();
		

Once instrumented, Service Bus operations appear as transactions and spans in the APM UI.

After configuring the agent and adding the Service Bus instrumentation package:

1. Ensure your application is running and connected to APM Server
2. Send or receive at least one Service Bus message
3. Open Kibana and navigate to Observability → Applications → Service inventory
4. Locate your service by name (configured in ELASTIC_APM_SERVICE_NAME)
5. Look for transactions and spans related to Service Bus operations

If you don't see data appearing, check:

• The APM Server URL and service name are correctly configured
• Network connectivity between your application and APM Server
• Application logs for any errors or warnings from the Elastic APM agent

Transactions represent the top-level operation, typically an inbound receive or message handler invocation. Spans represent child operations within an existing transaction, such as sending messages.

A new transaction is created when

• a receive operation is initiated against a queue or topic subscription (regardless of whether messages are returned).
• a receive deferred operation (retrieving a previously deferred message by sequence number) is initiated against a queue or topic subscription.
• a message is processed via ServiceBusProcessor or ServiceBusSessionProcessor — the push-based model where the SDK delivers messages to a registered handler. No additional code is required in your handler.

If a receive or receive deferred operation occurs within an existing transaction, a span is created instead.

A new span is created when there is a current transaction, and when

• one or more messages are sent to a queue or topic.
• one or more messages are scheduled to a queue or a topic.

When receiving or processing a batch of messages, the agent creates a span link for each message back to the producer span that sent it. This preserves the distributed trace across message boundaries and lets you follow each message end-to-end from producer to consumer in the APM UI.

Before Service Bus tracing will work, ensure the agent is connected to your APM Server. See Minimum configuration to configure:

• ELASTIC_APM_SERVER_URLS — APM Server endpoint
• ELASTIC_APM_SERVICE_NAME — Your application's name

Use IgnoreMessageQueues to exclude specific queues, topics, or subscriptions from being traced. This setting accepts a comma-separated list of wildcard patterns matched against the queue or topic name.

For all other agent configuration options, see Configuration.