Ruby OpenTelemetry Instrumentation

This guide shows you how to instrument your Ruby application including Rails, Sinatra, Sidekiq, Resque, Redis, and PostgreSQL with OpenTelemetry and send traces to SigNoz. The opentelemetry-instrumentation-all gem provides automatic instrumentation for 53+ popular Ruby libraries.

Prerequisites

• Ruby 3.2 or later
• Bundler installed
• A SigNoz Cloud account or self-hosted SigNoz instance

Send traces to SigNoz

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_SERVICE_NAME="<service-name>"

env:
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: 'https://ingest.<region>.signoz.cloud:443'
- name: OTEL_EXPORTER_OTLP_HEADERS
  value: 'signoz-ingestion-key=<your-ingestion-key>'
- name: OTEL_SERVICE_NAME
  value: '<service-name>'

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://ingest.<region>.signoz.cloud:443"
$env:OTEL_EXPORTER_OTLP_HEADERS = "signoz-ingestion-key=<your-ingestion-key>"
$env:OTEL_SERVICE_NAME = "<service-name>"

FROM ruby:3.3-alpine

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install

COPY . .

# Set OpenTelemetry environment variables
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
ENV OTEL_SERVICE_NAME="<service-name>"

EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]

docker run -e OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
    -e OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
    -e OTEL_SERVICE_NAME="<service-name>" \
    your-image:latest

Step 2. Install OpenTelemetry packages

Add the following gems to your Gemfile:

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

Run bundle install:

bundle install

The opentelemetry-instrumentation-all gem bundles 53+ library instrumentations including Rails, ActiveRecord, Sidekiq, Redis, and more.

Step 3. Configure OpenTelemetry SDK

Create an initializer file at config/initializers/opentelemetry.rb:

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

OpenTelemetry::SDK.configure do |c|
  c.use_all  # Enables all available instrumentations
end

The SDK automatically reads OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, and OTEL_EXPORTER_OTLP_HEADERS from the environment variables you set in Step 1.

Step 4. Run your application

Start your Rails server:

rails server

Your application is now instrumented and sending traces to SigNoz.

Library instrumentation

Choose your Ruby framework or library to add automatic instrumentation without leaving this page. Use the categories below to pick a specific integration.

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

OpenTelemetry::SDK.configure do |c|
  c.use_all({
    'OpenTelemetry::Instrumentation::Rails' => {
      enable_recognize_route: true,
    },
    'OpenTelemetry::Instrumentation::ActiveRecord' => {
      # Capture SQL queries in span attributes
      db_statement: :include,
    },
    'OpenTelemetry::Instrumentation::ActionPack' => {
      # Include controller and action in span names
      enable_recognize_route: true,
    },
  })
end

class OrdersController < ApplicationController
  def create
    tracer = OpenTelemetry.tracer_provider.tracer('my-rails-app')

    tracer.in_span('process-order') do |span|
      span.set_attribute('order.total', params[:total])
      span.add_event('order.validated')

      # Your order processing logic
      @order = Order.create!(order_params)

      span.set_attribute('order.id', @order.id)
    end

    render json: @order
  end
end

Validate

After running your instrumented application, verify traces appear in SigNoz:

1. Generate some traffic by making requests to your application.
2. Open SigNoz and navigate to Traces.
3. Click Refresh and look for new trace entries from your application.
4. Click on any trace to view detailed span information and timing.

echo $OTEL_EXPORTER_OTLP_ENDPOINT
echo $OTEL_SERVICE_NAME

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

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

Rails.logger.info "OpenTelemetry configured with service: #{ENV['OTEL_SERVICE_NAME']}"
Rails.logger.info "OpenTelemetry endpoint: #{ENV['OTEL_EXPORTER_OTLP_ENDPOINT']}"

# For SigNoz Cloud
curl -v https://ingest.<region>.signoz.cloud:443/v1/traces

# Verify instrumentations are loaded
puts OpenTelemetry.tracer_provider.tracer('test').class

# Option 1: Use the all-in-one gem (recommended)
gem 'opentelemetry-instrumentation-all'

# Option 2: Use individual gems (if you need only specific instrumentations)
# gem 'opentelemetry-instrumentation-rails'
# gem 'opentelemetry-instrumentation-sidekiq'

Next steps

• Need to create custom spans or add attributes yourself? Use the Manual Instrumentation in Ruby guide once the base setup is in place.
• Set up alerts for your Rails application
• Create dashboards to visualize metrics

Sample Ruby application

We have included a sample Ruby application with README.md at Sample Rails App Github Repo.