Seguimiento con OpenTelemetry

Overview

En esta guía, aprenderás a utilizar el trazado de OpenTelemetry con el controlador Ruby. OpenTelemetry es un framework de observación de código abierto que proporciona una forma estandarizada de instrumentar, generar, recopilar y exportar datos de telemetría.

El controlador Ruby admite la trazabilidad OpenTelemetry para ayudarle a comprender el rendimiento y el comportamiento de tus operaciones MongoDB. Cuando activas el rastreo, el controlador crea segmentos porque representan operaciones como consultas, actualizaciones y transacciones. Estos tramos incluyen atributos que siguen las convenciones semánticas de MongoDB.

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

Habilitar seguimiento de OpenTelemetry

Puede habilitar el rastreo 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
  }
)

Rastreo de operaciones

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

Rastreo de transacciones

El controlador crea un intervalo de transacción especial que abarca todas las operaciones dentro de una transacción explícita. El siguiente ejemplo demuestra 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 genera una jerarquía de span, 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 lapso utilizando el mecanismo de registro de excepciones de OpenTelemetry. El estado del lapso se establece en ERROR.

Para los fallos de operación de MongoDB, el atributo db.response.status_code contiene el código de error.

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:

• Cuando habilitas el seguimiento, el driver incurre en una sobrecarga mínima para la creación de spans y la colección de atributos.

• La captura de texto de query (db.query.text) tiene una sobrecarga adicional y debería usarse cuidadosamente en producción. Configurar query_text_max_length en 0 deshabilita la captura de texto de consultas para un mejor rendimiento.

• Cuando desactivas el rastreo, no hay impacto en el rendimiento porque la funcionalidad se omite completamente.

Ejemplo

El siguiente ejemplo muestra cómo configurar el rastreo 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 acerca del rastreo OpenTelemetry con Ruby, consulte el SDK Ruby de OpenTelemetry.