Rastrear operações com OpenTelemetry

Visão geral

Neste guia, você pode aprender a usar o rastreamento OpenTelemetry com o driver .NET/C#. OpenTelemetria é uma estrutura de observabilidade de código aberto que fornece uma maneira padronizada de instrumentar, gerar, coletar e exportar dados de telemetria.

O driver .NET/C# emite dados de rastreamento por meio do System.Diagnóstica.ActivitySource API. Quando você inscreve um ouvinte no ActivitySource do driver, o driver cria spans que representam suas operações do MongoDB , como queries e transações. Essas extensões incluem atributos que seguem as convenções semânticas do 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 rastreamento OpenTelemetry

O driver cria spans quando um ouvinte está inscrito no ActivitySource do driver e o cliente tem o rastreamento ativado. Para desabilitar o rastreamento para um cliente, defina a propriedade TracingOptions.Disabled como true.

Se nenhum ouvinte estiver inscrito, o driver pulará todo o trabalho de rastreamento e o impacto no desempenho será insignificante.

O driver registra seus spans em um ActivitySource chamado MongoDB.Driver. Para coletar os intervalos do driver, passe a constante MongoTelemetry.ActivitySourceName para o método AddSource() ao configurar o 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 opções de rastreamento

Para configurar o rastreamento para um cliente individual, defina a propriedade MongoClientSettings.TracingOptions para uma instância TracingOptions. A classe TracingOptions tem as seguintes propriedades:

O exemplo a seguir define QueryTextMaxLength como 1024, que captura até 1024 caracteres do texto do comando:

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

Rastreamento de operações

O driver .NET/C# cria os seguintes tipos de vãos:

Por exemplo, uma operação find cria uma extensão de nível de operação que contém uma extensão de nível de comando aninhada, como mostrado na seguinte hierarquia:

find sample_mflix.movies
  └── find

Segurança e redação

O motorista aplica as seguintes medidas de segurança para proteger informações confidenciais:

• O driver não cria períodos para comandos confidenciais, como comandos de autenticação. Estes comandos incluem authenticate, saslStart, saslContinue, getNonce, createUser, updateUser, copyDbSaslStart e copyDb. O driver também ignora o comando hello quando inclui o campospeculativeAuthenticate .

• O driver desabilita o atributo db.query.text por padrão. Ative este atributo somente quando necessário.

• Quando o driver captura o texto da query, ele remove os campos lsid, $db, $clusterTime e signature do comando.

Error Handling

Quando as operações falham, o driver registra os detalhes da exceção como atributos de extensão que seguem as convenções semânticas do OpenTelemetry e define o status da extensão como Error.

Para falhas de comando do MongoDB , o driver define o status da extensão de operação e de sua extensão de comando para Error. O driver registra o código de erro no atributo db.response.status_code na extensão de comando.

Erros de gravação que o servidor retorna em uma resposta de comando bem-sucedida, como um erro de chave duplicada, não definam db.response.status_code. O driver registra esses erros como atributos de exceção na extensão de operação.

Os erros não impedem que o driver aumente a exceção para o seu aplicativo.

Considerações de desempenho

Considere as seguintes implicações de desempenho ao usar o rastreamento OpenTelemetry:

• A captura do atributo db.query.text adiciona sobrecarga. Capture o texto de comando somente quando necessário ou defina QueryTextMaxLength como 0 para desativá-lo.

• Quando nenhum ouvinte está inscrito no ActivitySource do driver, o rastreamento tem um impacto insignificante no desempenho porque o driver ignora todo o trabalho de rastreamento.

Informações adicionais

Para saber mais sobre o rastreamento do OpenTelemetry, consulte a documentação do OpenTelemetry .NET .