Rastreie com OpenTelemetry

Visão geral

Neste guia, você aprenderá como usar o rastreamento OpenTelemetry com o driver Ruby. OpenTelemetry é uma estrutura de observabilidade de código aberto que fornece uma maneira padronizada de instrumentar, gerar, coletar e exportar dados de telemetria.

O driver Ruby suporta rastreamento OpenTelemetry para ajudá-lo a entender o desempenho e o comportamento de suas operações do MongoDB . Quando você habilita o rastreamento, o driver cria spans que representam operações como queries, atualizações e transações. Esses spans incluem atributos que seguem as convenções semânticas do MongoDB .

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'  # or your preferred exporter

Habilitar rastreamento OpenTelemetry

Você pode ativar o rastreamento OpenTelemetry especificando a opção tracing ao criar um cliente ou definindo uma variável de ambiente.

client = Mongo::Client.new(['localhost:27017'], 
  database: 'my_database',
  tracing: {
    enabled: true
  }
)

export OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED=true

client = Mongo::Client.new(['localhost:27017'], 
  database: 'my_database')

Opções de configuração

A opção tracing aceita os seguintes parâmetros:

O exemplo a seguir mostra como configurar todas as opções de rastreamento disponíveis:

client = Mongo::Client.new(['localhost:27017'],
  database: 'my_database',
  tracing: {
    enabled: true,
    query_text_max_length: 1024,
    tracer: my_custom_tracer
  }
)

Rastreamento de operações

O driver Ruby cria vãos OpenTelemetry para operações de alto nível e comandos de baixo nível. As seções a seguir descrevem as extensões criadas e os atributos incluídos.

Rastreamento de transações

O driver cria uma extensão de transação especial que engloba todas as operações dentro de uma transação explícita. O exemplo a seguir demonstra o rastreamento de transações:

session = client.start_session
session.with_transaction do
  collection.insert_one({ name: 'Alice' }, session: session)
  collection.update_one(
    { name: 'Bob' }, 
    { '$set' => { age: 30 } }, 
    session: session
  )
end

O exemplo anterior produz uma hierarquia de extensão semelhante à seguinte estrutura:

transaction
  └── insertOne.users
      └── insert (command)
  └── updateOne.users
      └── update (command)

Error Handling

Quando as operações falham, o driver registra exceções no intervalo usando o mecanismo de registro de exceções do OpenTelemetry. O status da extensão é então definido como ERROR.

Para falhas de operação MongoDB , o atributo db.response.status_code contém o código de erro.

Os erros não impedem que o condutor aumente a exceção para a sua aplicação.

Considerações de desempenho

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

• Ao ativar o rastreamento, o driver incorre em sobrecarga mínima para a criação de extensão e a coleta de atributos.

• A captura de texto da query (db.query.text) tem uma sobrecarga adicional e você deve usá-la cuidadosamente na produção. A definição de query_text_max_length para 0 desativa a captura de texto da query para melhor desempenho.

• Quando você desabilita o rastreamento, não há impacto no desempenho porque o recurso é completamente ignorado.

Exemplo

O exemplo a seguir mostra como configurar o rastreamento OpenTelemetry para um aplicação MongoDB :

require 'mongo'
require 'opentelemetry/sdk'
# Configure OpenTelemetry
OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-app'
end
# Create MongoDB client with tracing enabled
client = Mongo::Client.new(['localhost:27017'],
  database: 'test',
  tracing: { 
    enabled: true,
    query_text_max_length: 1024 
  }
)
# Use the client normally - operations are traced
collection = client[:users]
collection.insert_one({ name: 'Alice', age: 30 })
collection.find({ age: { '$gte': 25 } }).to_a

Informações adicionais

Para saber mais sobre o rastreamento OpenTelemetry com Ruby, consulte o SDK Ruby do OpenTelemetry.