OpenTelemetry (OTLP)

The OTLP integration configures the Sentry SDK to automatically send trace data instrumented by an OpenTelemetry SDK to Sentry's OpenTelemetry Protocol ingestion endpoint.

Install

Add the following gems to your Gemfile:

gem "sentry-ruby"
gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"

# Add any OpenTelemetry instrumentation gems you need, for example:
gem "opentelemetry-instrumentation-all"

gem "sentry-ruby"
gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"

# Add any OpenTelemetry instrumentation gems you need, for example:
gem "opentelemetry-instrumentation-all"

Then run:

bundle install

bundle install

Configure

You need to configure both the OpenTelemetry and Sentry SDKs to get trace data.

OpenTelemetry

For the OpenTelemetry SDK, you need to configure instrumentation you want to capture.

OpenTelemetry::SDK.configure do |c|
  c.use_all # or configure specific instrumentations
end

OpenTelemetry::SDK.configure do |c|
  c.use_all # or configure specific instrumentations
end

Sentry

For the Sentry SDK, enable the OTLP integration in your existing configuration. The integration links OpenTelemetry spans to Sentry events by default. To automatically export traces to Sentry, also enable the OTLP exporter:

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.otlp.enabled = true
  config.otlp.setup_otlp_traces_exporter = true

  # Enable this for Distributed Tracing with other services using Sentry SDKs.
  # config.otlp.setup_propagator = true
end

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.otlp.enabled = true
  config.otlp.setup_otlp_traces_exporter = true

  # Enable this for Distributed Tracing with other services using Sentry SDKs.
  # config.otlp.setup_propagator = true
end

Behavior

When enabled, the OTLP integration sets up the following parts:

• Trace/Span linking for all other Sentry events such as Errors, Logs, and Metrics
• A SpanExporter when setup_otlp_traces_exporter is true. The exporter automatically configures the OTLP ingestion endpoint from your Sentry DSN. This enables tracing in Sentry. Note: Do not also set up tracing via the Ruby SDK (that is, don't set traces_sample_rate or instrumenter).
• A Sentry Propagator when setup_propagator is true, for compatibility with services using Sentry's native tracing

Cross-service trace propagation between OpenTelemetry services uses OTel's default W3C traceparent headers and doesn't require additional configuration. See Exporters, Event Linking, and Propagation for details.

Options

You can configure the following options on config.otlp:

• enabled:

  Enable the OTLP integration, defaults to false.

• setup_otlp_traces_exporter:

  Automatically configure an Exporter to send OTLP traces to the right project from the DSN or collector_url, defaults to false.

  Leave this set to false to set up the TracerProvider manually.

• collector_url:

  URL of your own OpenTelemetry collector. When setup_otlp_traces_exporter is true, the exporter sends traces to this URL instead of the Sentry OTLP endpoint derived from the DSN.

• setup_propagator:

  Automatically configure the Sentry propagator for distributed tracing, defaults to false.

  Leave this set to false to configure propagators manually or to disable propagation.

  Planned Removal

  The automatic propagator setup will be removed in the next major version. Configure propagators manually using the OpenTelemetry propagation API instead.

Supported Versions

• Ruby: 2.7+
• sentry-ruby: 6.4.0+
• opentelemetry-sdk: 1.0+