Ruby and Ruby on Rails

Send OpenTelemetry traces from Ruby and Ruby on Rails applications to KubeSense.

Ruby applications are instrumented with the OpenTelemetry Ruby SDK and the opentelemetry-instrumentation-all gem. It creates spans for Rails (Action Pack, Action View, Active Record), Sinatra, Rack, HTTP clients (Net::HTTP, Faraday), Redis, Sidekiq and other libraries. Ruby uses manual setup: you add the gems and one initializer file to the application. After that, all supported libraries are instrumented automatically, with no further code changes.

note: The OpenTelemetry Operator does not support Ruby injection. On Kubernetes, use the steps below and set the environment variables in your manifest.

Step 1: Install the gems

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

Gem	Purpose
`opentelemetry-sdk`	Core OpenTelemetry SDK for Ruby
`opentelemetry-exporter-otlp`	Exports spans over OTLP/HTTP. Without it, no data is sent
`opentelemetry-instrumentation-all`	Instrumentation for Rails, Sinatra, Rack, HTTP clients, databases, Sidekiq and more

Step 2: Initialize OpenTelemetry

Ruby on Rails

Create config/initializers/opentelemetry.rb:

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  # The service name is read from OTEL_SERVICE_NAME; this is only a fallback.
  c.service_name = ENV.fetch('OTEL_SERVICE_NAME', 'rails-app')
  c.use_all # enable every available instrumentation
end

Other Ruby applications (Sinatra, Rack, plain Ruby)

Load your framework first, then run the configuration before your application code, for example at the top of config.ru:

require 'sinatra'   # your framework

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

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

require_relative 'app'

Step 3: Configure the exporter

OTEL_SERVICE_NAME=billing-api
OTEL_EXPORTER_OTLP_ENDPOINT=http://<KUBESENSE_INGEST_HOST>:33443
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES=kubesense.cluster=<CLUSTER_NAME>,kubesense.env_type=legacy

Variable	Notes
`OTEL_EXPORTER_OTLP_ENDPOINT`	Base URL; `/v1/traces` is appended automatically. Inside the KubeSense cluster, use `http://kubesense-kubecol.kubesense.svc.cluster.local:33443`, or your OpenTelemetry Collector (`:4318`)
`OTEL_RESOURCE_ATTRIBUTES`	Use `kubesense.env_type=k8s` on Kubernetes and `legacy` elsewhere

On Kubernetes:

env:
  - name: OTEL_SERVICE_NAME
    value: billing-api
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://kubesense-kubecol.kubesense.svc.cluster.local:33443
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: http/protobuf
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: kubesense.cluster=<CLUSTER_NAME>,kubesense.env_type=k8s

note: This setup exports traces only. Application logs are collected by the KubeSense log sensor.

Step 4: Run and verify

Start the application as usual:

bundle exec rails server
# or
bundle exec puma
# or
ruby app.rb

Generate some traffic, then open APM → Traces in KubeSense and filter by your service name.

Background jobs (Sidekiq)

Sidekiq is instrumented automatically, and job spans are linked to the request that enqueued them. Give the worker process its own name, so it appears as a separate service:

OTEL_SERVICE_NAME=billing-worker bundle exec sidekiq

Turning off a specific instrumentation

Pass options to use_all:

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

Troubleshooting

Set OTEL_LOG_LEVEL=debug temporarily to see export activity in the application log.

Symptom	Check
Log message that the OTLP exporter gem is not installed	Add `opentelemetry-exporter-otlp` to the Gemfile
No spans for Rails requests	The initializer must be in `config/initializers/`, and `c.use_all` must be called
Connection errors to `:33443`	Trace ingestion is not enabled on KubeSense, or the port is not reachable
All processes appear as one service	Set a different `OTEL_SERVICE_NAME` for web and worker processes

Ruby and Ruby on Rails

ON THIS PAGE