Last updated: August 7, 2026
Getting Started
Note: This page is auto-generated from the opentelemetry-ruby-distribution repository.
The primary use case for this distribution is injection into Ruby workloads by the Dash0 Kubernetes operator, which performs everything described on this page for you.
If that is your intended use case, skip to Kubernetes injection.
Read on to install dash0-opentelemetry as a standalone gem, for example for local development or a deployment outside Kubernetes.
Install the gem
Install dash0-opentelemetry outside the application's bundle:
1gem install dash0-opentelemetry
The distribution ships its own gem closure (OpenTelemetry SDK, exporters, and all instrumentation libraries).
It must be installed outside the application bundle because it loads OpenTelemetry from its own gem path, not from the application's Gemfile.
Start the application
Set two environment variables and start the application as usual:
123export DASH0_OTEL_COLLECTOR_BASE_URL=http://your-collector:4318export RUBYOPT="-r dash0-opentelemetry"ruby your_app.rb
For Rails:
123export DASH0_OTEL_COLLECTOR_BASE_URL=http://your-collector:4318export RUBYOPT="-r dash0-opentelemetry"rails server
On startup the distribution exports traces, metrics, and logs to ${DASH0_OTEL_COLLECTOR_BASE_URL}/v1/{traces,metrics,logs}.
Export directly to Dash0
To export directly to Dash0 without a local collector, use your organization's Dash0 ingress URL and an authorization token:
1234export DASH0_OTEL_COLLECTOR_BASE_URL=<your-dash0-ingress-url>export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-token>"export RUBYOPT="-r dash0-opentelemetry"rails server
Startup sequence
When the application starts, the distribution:
- Checks the Ruby version; stands down cleanly on Ruby older than 3.3.
- Checks
DASH0_DISABLE; stands down if set totrue. - Checks
DASH0_OTEL_COLLECTOR_BASE_URL; stands down if unset. - Checks whether the OpenTelemetry SDK is already loaded; stands down if so, to avoid double instrumentation.
- Configures the OpenTelemetry SDK with OTLP/HTTP exporters and Dash0 resource attributes.
- Installs all supported instrumentations for libraries already loaded, then installs a
TracePointto catch libraries loaded later. - Installs lifecycle handlers (SIGTERM/SIGINT flush if configured;
at_exitflush by default).