Skip to main content

Ruby

This guide walks you through setting up OpenTelemetry in your Ruby application and exporting traces to CtrlB. The opentelemetry-instrumentation-all gem provides automatic instrumentation for 53+ popular Ruby libraries including Rails, Sinatra, Faraday, and more.

OpenTelemetry SDK status (mid-2026): Ruby trace instrumentation is Stable. See the OpenTelemetry language status table.

Prerequisites​

Step 1. Install Dependencies​

You can install OpenTelemetry in two main ways—depending on whether you want all instrumentations or just specific ones.

Add the OpenTelemetry SDK, OTLP exporter, and the metapackage that includes all instrumentation libraries to your Gemfile:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

If you prefer to install only specific instrumentation, add the specific instrumentation libraries to your Gemfile:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-sinatra'
gem 'opentelemetry-instrumentation-faraday'
# Add other specific instrumentations as needed

Install gems added to the Gemfile​

bundle install

Step 2. Configure OpenTelemetry Instrumentation​

Once dependencies are installed, you can configure OpenTelemetry in your application. You can write the configuration in a Rails initializer file like config/initializers/opentelemetry.rb.

A. Configure all instrumentation libraries​

If you installed opentelemetry-instrumentation-all, you can enable all instrumentations easily.

Example (Rails initializer):

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.use_all # enables all instrumentation
end

This automatically enables all supported libraries detected in your app.

B. Override configuration for specific libraries​

If you want to disable or modify specific instrumentations while using use_all, you can provide a configuration map.

Example: Disable Redis instrumentation

require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  config = { 'OpenTelemetry::Instrumentation::Redis' => { enabled: false } }
  c.use_all(config)
end

To override multiple libraries, add more entries to the config hash.

C. Configure specific instrumentation libraries only​

If you prefer to use only certain instrumentations, explicitly enable them:

require 'opentelemetry/sdk'

OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::Sinatra'
  c.use 'OpenTelemetry::Instrumentation::Faraday', { opt: 'value' }
end

Use this approach for production deployments where you want tight control over instrumentation. To explore the full range of Ruby instrumentation options, refer to the following resources:

Step 3. Configure Exporter for CtrlB​

Once your application is instrumented, configure the OTLP exporter to send telemetry data directly to CtrlB.

Set the following environment variables before starting your app:

OTEL_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_SERVICE_NAME=<service_name> \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<INGESTION_HOST>/api/default/v1/traces \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <API_TOKEN>,stream-name=<STREAM_NAME>" \
rails server
Instrument all telemetry together

The block above sends traces only. To export traces, metrics, and logs from the same application, use the shared OTLP endpoint and headers instead of the signal-specific endpoint above:

OTEL_EXPORTER_OTLP_ENDPOINT=https://<INGESTION_HOST>/api/default \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://<INGESTION_HOST>/api/default/<STREAM_NAME>/_otel/v1/logs \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <API_TOKEN>,stream-name=<STREAM_NAME>"

Step 4. Use OpenTelemetry Collector (Optional)​

For production setups, it’s recommended to send traces through an OpenTelemetry Collector before CtrlB. This enables buffering, batching, retries, and multi-sink routing.

See OpenTelemetry Collector for Traces for configuration details.

See Also​