Seguimiento con OpenTelemetry

Overview

En esta guía, aprenderá a utilizar el seguimiento de OpenTelemetry con el controlador Ruby. 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 Ruby admite el seguimiento de OpenTelemetry para ayudarle a comprender el rendimiento y el comportamiento de sus operaciones de MongoDB. Al habilitar el seguimiento, el controlador crea intervalos que representan operaciones como consultas, actualizaciones y transacciones. Estos intervalos incluyen atributos que siguen las convenciones semánticas de MongoDB.

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

Habilitar el seguimiento de OpenTelemetry

Puede habilitar el seguimiento de OpenTelemetry especificando la opción tracing al crear un cliente o configurando una variable de entorno.

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')

Opciones de configuración

La opción tracing acepta los siguientes parámetros:

El siguiente ejemplo muestra cómo configurar todas las opciones de seguimiento disponibles:

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

Operación Rastreo

El controlador Ruby crea intervalos de OpenTelemetry tanto para operaciones de alto nivel como para comandos de bajo nivel. Las siguientes secciones describen los intervalos creados y los atributos incluidos.

Rastreo de transacciones

El controlador crea un intervalo de transacciones especial que abarca todas las operaciones dentro de una transacción explícita. El siguiente ejemplo muestra el seguimiento de transacciones:

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

El ejemplo anterior produce una jerarquía de tramos similar a la siguiente estructura:

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

Error Handling

Cuando las operaciones fallan, el controlador registra las excepciones en el intervalo mediante el mecanismo de registro de excepciones de OpenTelemetry. El estado del intervalo se establece entonces en ERROR.

En caso de fallas en la operación de MongoDB, el atributo db.response.status_code contiene el código de error.

Los errores no impiden que el controlador genere la excepción en su aplicación.

Consideraciones sobre el rendimiento

Tenga en cuenta las siguientes implicaciones de rendimiento cuando utilice el seguimiento de OpenTelemetry:

• Cuando habilita el seguimiento, el controlador incurre en una sobrecarga mínima para la creación de intervalos y la recopilación de atributos.

• La captura de texto de consulta (db.query.text) implica una sobrecarga adicional y se recomienda usarla con precaución en producción. Al establecer query_text_max_length en 0, se deshabilita la captura de texto de consulta para un mejor rendimiento.

• Al deshabilitar el seguimiento, no hay impacto en el rendimiento porque la función se omite por completo.

Ejemplo

El siguiente ejemplo muestra cómo configurar el seguimiento de OpenTelemetry para una aplicación 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

Información Adicional

Para obtener más información sobre el seguimiento de OpenTelemetry con Ruby, consulte el SDK de OpenTelemetry Ruby.