Set up Azure Cosmos DB instrumentation

For the full compatibility matrix including supported installation methods, refer to Data access technologies.

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.CosmosDb NuGet package to your project:

dotnet add package Elastic.Apm.Azure.CosmosDb
		

Subscribe to diagnostic events once at application startup:

using Elastic.Apm;
using Elastic.Apm.Azure.CosmosDb;

Agent.Subscribe(new AzureCosmosDbDiagnosticsSubscriber());
		

HTTP-based diagnostic events from Microsoft.Azure.Cosmos, Microsoft.Azure.DocumentDb, and Microsoft.Azure.DocumentDb.Core are captured as DB spans. This covers Gateway mode only. Because CosmosClient defaults to Direct mode (TCP), most applications also need the additional setup described in Direct mode (TCP) below to capture CRUD and query spans.

CosmosClient supports two connection modes, which affect how operations are instrumented.

CosmosClient defaults to Direct mode, which routes data-plane requests over the RNTBD TCP protocol, bypassing HTTP entirely. The Elastic.Apm.Azure.CosmosDb package does not observe these requests, so CRUD and query operations produce no spans by default in Direct mode.

To capture Direct-mode operations, enable built-in OpenTelemetry support in the Cosmos SDK (requires Microsoft.Azure.Cosmos ≥ 3.36.0). The APM agent's OpenTelemetry bridge (enabled by default) captures the resulting Azure.Cosmos.Operation activities as db/cosmosdb spans.

Set the following once at application startup, before creating any CosmosClient instance:

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
		

You must also explicitly enable distributed tracing on the client — it is turned off by default in stable SDK releases:

var client = new CosmosClient(connectionString, new CosmosClientOptions
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions
    {
        DisableDistributedTracing = false
    }
});
		

When CosmosClient is configured with ConnectionMode.Gateway (or when using the Cosmos emulator), data-plane requests travel over HTTPS. The Elastic.Apm.Azure.CosmosDb package intercepts these HTTP requests and captures them as db/cosmosdb spans with operation names such as Cosmos DB Create/query document.

No additional configuration is required beyond the preceding quick-start steps.