Trace Operations with OpenTelemetry

Overview

In this guide, you can learn how to use OpenTelemetry tracing with the .NET/C# Driver. OpenTelemetry is an open source observability framework that provides a standardized way to instrument, generate, collect, and export telemetry data.

The .NET/C# Driver emits trace data through the System.Diagnostics.ActivitySource API. When you subscribe a listener to the driver's ActivitySource, the driver creates spans that represent your MongoDB operations, such as queries and transactions. These spans include attributes that follow OpenTelemetry semantic conventions.

var connectionString = "<connection string>";
var client = new MongoClient(connectionString);
var collection = client.GetDatabase("sample_mflix").GetCollection<BsonDocument>("movies");

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.InMemory

Enable OpenTelemetry Tracing

The driver creates spans when a listener is subscribed to the driver's ActivitySource and the client has tracing enabled. To disable tracing for a client, set the TracingOptions.Disabled property to true.

If no listener is subscribed, the driver skips all tracing work and the performance impact is negligible.

The driver registers its spans on an ActivitySource named MongoDB.Driver. To collect the driver's spans, pass the MongoTelemetry.ActivitySourceName constant to the AddSource() method when you configure OpenTelemetry.

dotnet add package OpenTelemetry.Extensions.Hosting

// Register the driver's ActivitySource with an OpenTelemetry
// TracerProvider in a generic host.
var exportedSpans = new List<Activity>();
var builder = Host.CreateApplicationBuilder();
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(MongoTelemetry.ActivitySourceName)
        .AddInMemoryExporter(exportedSpans));
var host = builder.Build();

// Register the driver's ActivitySource with an OpenTelemetry
// TracerProvider.
var exportedSpans = new List<Activity>();
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(MongoTelemetry.ActivitySourceName)
    .AddInMemoryExporter(exportedSpans)
    .Build();

var filter = Builders<BsonDocument>.Filter.Eq("title", "Back to the Future");
var movie = collection.Find(filter).First();

{ "name" : "find sample_mflix.movies", "kind" : "operation" }
{ "name" : "find", "kind" : "command" }

// Subscribe to the driver's ActivitySource by using an ActivityListener.
// This approach avoids a dependency on the OpenTelemetry SDK.
var exportedSpans = new List<Activity>();
using var listener = new ActivityListener
{
    ShouldListenTo = source => source.Name == MongoTelemetry.ActivitySourceName,
    Sample = (ref ActivityCreationOptions<ActivityContext> _) =>
        ActivitySamplingResult.AllDataAndRecorded,
    ActivityStopped = exportedSpans.Add
};
ActivitySource.AddActivityListener(listener);

Configure Tracing Options

To configure tracing for an individual client, set the MongoClientSettings.TracingOptions property to a TracingOptions instance. The TracingOptions class has the following properties:

The following example sets QueryTextMaxLength to 1024, which captures up to 1024 characters of the command text:

var settings = MongoClientSettings.FromConnectionString(connectionString);
settings.TracingOptions = new TracingOptions
{
    Disabled = false,
    QueryTextMaxLength = 1024
};
var client = new MongoClient(settings);

Operation Tracing

The .NET/C# Driver creates the following types of spans:

For example, a find operation creates an operation-level span that contains a nested command-level span, as shown in the following hierarchy:

find sample_mflix.movies
  └── find

Security and Redaction

The driver applies the following security measures to protect sensitive information:

• The driver does not create spans for sensitive commands, such as authentication commands. These commands include authenticate, saslStart, saslContinue, getNonce, createUser, updateUser, copyDbSaslStart, and copyDb. The driver also skips the hello command when it includes the speculativeAuthenticate field.

• The driver disables the db.query.text attribute by default. Enable this attribute only when necessary.

• When the driver captures query text, it removes the lsid, $db, $clusterTime, and signature fields from the command.

Error Handling

When operations fail, the driver records the exception details as span attributes that follow OpenTelemetry semantic conventions and sets the span status to Error.

For MongoDB command failures, the driver sets the status of both the operation span and its command span to Error. The driver records the error code in the db.response.status_code attribute on the command span.

Write errors that the server returns in a successful command response, such as a duplicate key error, do not set db.response.status_code. The driver records these errors as exception attributes on the operation span.

Errors do not prevent the driver from raising the exception to your application.

Performance Considerations

Consider the following performance implications when you use OpenTelemetry tracing:

• Capturing the db.query.text attribute adds overhead. Capture command text only when necessary, or set QueryTextMaxLength to 0 to disable it.

• When no listener is subscribed to the driver's ActivitySource, tracing has negligible performance impact because the driver skips all tracing work.

Additional Information

To learn more about OpenTelemetry tracing, see the OpenTelemetry .NET documentation.