Operaciones de seguimiento con OpenTelemetry

Overview

En esta guía, aprenderá a usar el rastreo de OpenTelemetry con el controlador .NET/C#. OpenTelemetry es un marco de observabilidad de código abierto que proporciona una forma estandarizada de instrumentar, generar, recopilar y exportar datos de telemetría.

El controlador .NET/C# emite datos de seguimiento a través de la API System.Diagnostics.ActivitySource. Al suscribir un oyente al ActivitySource del controlador, este crea segmentos que representan las operaciones de MongoDB, como consultas y transacciones. Estos segmentos incluyen atributos que siguen las convenciones semánticas de OpenTelemetry.

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

Habilitar seguimiento de OpenTelemetry

El controlador crea tramos cuando un oyente está suscrito al ActivitySource del controlador y el cliente tiene habilitado el rastreo. Para deshabilitar el rastreo para un cliente, establezca la propiedad TracingOptions.Disabled en true.

Si ningún oyente está suscrito, el controlador omite todo el trabajo de rastreo y el impacto en el rendimiento es insignificante.

El controlador registra sus segmentos en un ActivitySource llamado MongoDB.Driver. Para recopilar los segmentos del controlador, pase la constante MongoTelemetry.ActivitySourceName al método AddSource() cuando 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);

Configurar opciones de rastreo

Para configurar el rastreo para un cliente individual, establezca la propiedad MongoClientSettings.TracingOptions en una instancia de TracingOptions. La clase TracingOptions tiene las siguientes propiedades:

El siguiente ejemplo establece QueryTextMaxLength a 1024, lo que captura hasta 1024 caracteres del texto del comando:

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

Rastreo de operaciones

El controlador .NET/C# crea los siguientes tipos de tramos:

Por ejemplo, una operación find crea un segmento a nivel de operación que contiene un segmento anidado a nivel de comando, como se muestra en la siguiente jerarquía:

find sample_mflix.movies
  └── find

Seguridad y redacción

El conductor aplica las siguientes medidas de seguridad para proteger la información confidencial:

• El controlador no crea segmentos para comandos confidenciales, como los comandos de autenticación. Estos comandos incluyen authenticate, saslStart, saslContinue, getNonce, createUser, updateUser, copyDbSaslStart y copyDb. El controlador también omite el comando hello cuando incluye el campo speculativeAuthenticate.

• El controlador desactiva el atributo db.query.text por defecto. Active este atributo solo cuando sea necesario.

• Cuando el controlador captura el texto de la consulta, elimina los campos lsid, $db, $clusterTime y signature del comando.

Error Handling

Cuando las operaciones fallan, el controlador registra los detalles de la excepción como atributos de span que siguen las convenciones semánticas de OpenTelemetry y establece el estado del span en Error.

En caso de fallos en los comandos de MongoDB, el controlador establece el estado tanto del segmento de operación como de su segmento de comando en Error. El controlador registra el código de error en el atributo db.response.status_code del segmento de comando.

Los errores que el servidor devuelve en una respuesta de comando exitosa, como un error de clave duplicada, no se establecen en db.response.status_code. El controlador registra estos errores como atributos de excepción en el segmento de operación.

Los errores no impiden que el controlador lance la excepción a su aplicación.

Consideraciones sobre el rendimiento

Tenga en cuenta las siguientes implicaciones de rendimiento cuando utilice la trazabilidad de OpenTelemetry:

• La captura del atributo db.query.text genera sobrecarga. Capture el texto del comando solo cuando sea necesario, o establezca QueryTextMaxLength en 0 para deshabilitarlo.

• Cuando ningún oyente está suscrito al ActivitySource del controlador, el rastreo tiene un impacto insignificante en el rendimiento porque el controlador omite todo el trabajo de rastreo.

Información Adicional

Para obtener más información sobre el rastreo de OpenTelemetry, consulte la documentación de OpenTelemetry.NET.