Trace with OpenTelemetry

Overview

In this guide, you will learn how to use OpenTelemetry tracing with the Ruby driver. OpenTelemetry is an open source observability framework that provides a standardized way to instrument, generate, collect, and export telemetry data.

The Ruby driver supports OpenTelemetry tracing to help you understand the performance and behavior of your MongoDB operations. When you enable tracing, the driver creates spans that represent operations such as queries, updates, and transactions. These spans include attributes that follow MongoDB semantic conventions.

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

Enable OpenTelemetry Tracing

You can enable OpenTelemetry tracing by specifying the tracing option when you create a client, or by setting an environment variable.

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

Configuration Options

The tracing option accepts the following parameters:

The following example shows how to configure all available tracing options:

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

Operation Tracing

The Ruby driver creates OpenTelemetry spans for both high-level operations and low-level commands. The following sections describe the spans created and the attributes included.

Transaction Tracing

The driver creates a special transaction span that encompasses all operations within an explicit transaction. The following example demonstrates transaction tracing:

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

The preceding example produces a span hierarchy similar to the following structure:

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

Error Handling

When operations fail, the driver records exceptions in the span by using OpenTelemetry's exception recording mechanism. The span status is then set to ERROR.

For MongoDB operation failures, the db.response.status_code attribute contains the error code.

Errors do not prevent the driver from raising the exception to your application.

Performance Considerations

Consider the following performance implications when you use OpenTelemetry tracing:

• When you enable tracing, the driver incurs minimal overhead for span creation and attribute collection.

• Query text capture (db.query.text) has additional overhead and you should use it judiciously in production. Setting query_text_max_length to 0 disables query text capture for better performance.

• When you disable tracing, there is no performance impact because the feature is completely bypassed.

Example

The following example shows how to set up OpenTelemetry tracing for a MongoDB application:

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

Additional Information

To learn more about OpenTelemetry tracing with Ruby, see the OpenTelemetry Ruby SDK.