Ruby OpenTelemetry instrumentation

Instrument a Ruby on Rails application with OpenTelemetry using the opentelemetry-instrumentation-all gem, which installs instrumentation for Rails, Active Record, Rack, Net::HTTP, and the other libraries in a typical Rails stack. Requests, database queries, and outbound calls are traced with a single initializer.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument ruby

The agent adds the OpenTelemetry gems, writes the initializer, and sets the exporter environment variables for your service.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

• A Ruby on Rails application (the same setup works for Sinatra or any Rack app).
• Ruby 3.0 or newer.
• Your Osuite ingest token and region.

Install and configure

1. Add the SDK, the OTLP exporter, and the all-in-one instrumentation gem to your bundle.

   bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

2. Create config/initializers/opentelemetry.rb and configure the SDK. c.use_all enables every bundled instrumentation library it detects.

   require 'opentelemetry/sdk'
   require 'opentelemetry/exporter/otlp'
   require 'opentelemetry/instrumentation/all'
   
   OpenTelemetry::SDK.configure do |c|
     c.service_name = '<service-name>'
     c.use_all
   end

3. Set the exporter environment variables.

   export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443
   export OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token>
   export OTEL_SERVICE_NAME=<service-name>
   export OTEL_RESOURCE_ATTRIBUTES=service.environment=production

   OTEL_SERVICE_NAME and c.service_name in the initializer set the same thing — the explicit c.service_name above wins, so keep the two in sync or drop one of them.

   The https:// scheme is required — the OTLP exporter takes a URL and Osuite only accepts OTLP over TLS.

Run Rails with instrumentation

The initializer loads at boot, so no change to how you start the app is needed:

rails server

Configure OpenTelemetry per worker in clustered servers

Puma in clustered mode and Unicorn fork worker processes after boot. The exporter’s background thread does not survive the fork, so configure the SDK inside the server’s post-fork hook — on_worker_boot in config/puma.rb, or after_fork in Unicorn — so each worker gets its own exporter. A single-process server needs no hook.

Verify in Osuite

What you should see

Send a request to any route. The service appears in APM within a minute with a trace per request, showing the controller action, Active Record queries, and outbound HTTP calls as nested spans.

Troubleshooting

If no traces appear, confirm the initializer ran (Rails logs OpenTelemetry::SDK instrumentation messages at boot) and that the environment variables are set in the process that serves requests. In clustered Puma or Unicorn, move OpenTelemetry::SDK.configure into the post-fork hook as noted above.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

Next steps

Already using OpenTelemetry? Point an existing OpenTelemetry setup at Osuite by changing the endpoint.

Explore traces Open the trace explorer and service map in Osuite.