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+
- Bundler installed
- A SigNoz Cloud account or self-hosted SigNoz instance
Send traces to SigNoz
Step 1. Set environment variables
Set the following environment variables to configure the OpenTelemetry exporter:
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>"
export OTEL_RESOURCE_ATTRIBUTES="service.version=<service-version>"
Verify these values:
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key.<service-name>: A descriptive name for your service (e.g.,my-rails-app).<service-version>(optional): Your release version, image tag, or git SHA (e.g.,1.4.2,a01dbef8).
Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes: inject from your Helm chart image tag or CI variable
Step 1. Set environment variables
Add these environment variables to your deployment manifest:
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>'
- name: OTEL_RESOURCE_ATTRIBUTES
value: 'service.version=<service-version>'
Verify these values:
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key.<service-name>: A descriptive name for your service (e.g.,my-rails-app).<service-version>(optional): Your release version, image tag, or git SHA (e.g.,1.4.2,a01dbef8).
Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes: inject from your Helm chart image tag or CI variable
Step 1. Set environment variables (PowerShell)
$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>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.version=<service-version>"
Verify these values:
<region>: Your SigNoz Cloud region.<your-ingestion-key>: Your SigNoz ingestion key.<service-name>: A descriptive name for your service.<service-version>(optional): Your release version, image tag, or git SHA (e.g.,1.4.2,a01dbef8).
Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes: inject from your Helm chart image tag or CI variable
Step 1. Set environment variables in Dockerfile
Add environment variables to your Dockerfile:
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>"
ENV OTEL_RESOURCE_ATTRIBUTES="service.version=<service-version>"
EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]
Or pass them at runtime using docker run:
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>" \
-e OTEL_RESOURCE_ATTRIBUTES="service.version=<service-version>" \
your-image:latest
Verify these values:
<region>: Your SigNoz Cloud region<your-ingestion-key>: Your SigNoz ingestion key.<service-name>: A descriptive name for your service (e.g.,my-rails-app).<service-version>(optional): Your release version, image tag, or git SHA (e.g.,1.4.2,a01dbef8).
Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes: inject from your Helm chart image tag or CI variable
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.
If you don't set OTEL environment variables in development, the SDK will attempt to export to http://localhost:4318 (the OTel Collector default), which may produce noise or errors. Add an environment guard to skip initialization in development:
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
unless Rails.env.development?
OpenTelemetry::SDK.configure do |c|
c.use_all
end
end
This prevents noisy connection errors in development when OTEL env vars aren't set, such as when running rails console.
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.
Web Frameworks
Rails
This guide shows you how to configure OpenTelemetry instrumentation for Rails. Complete the core Rails instrumentation setup first.
The opentelemetry-instrumentation-all gem automatically instruments Rails components including ActionPack, ActionView, and ActiveRecord.
Configure specific instrumentations
You can customize individual instrumentations by passing options:
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
What gets instrumented automatically
- ActionPack: HTTP request handling, controller actions
- ActionView: Template rendering
- ActiveRecord: Database queries
- ActiveJob: Background job processing
- ActionMailer: Email sending
Adding manual spans
Create custom child spans to trace specific operations:
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:
- Generate some traffic by making requests to your application.
- Open SigNoz and navigate to Traces.
- Click Refresh and look for new trace entries from your application.
- Click on any trace to view detailed span information and timing.
Troubleshooting
Why don't traces appear in SigNoz?
Check environment variables are set:
echo $OTEL_EXPORTER_OTLP_ENDPOINT
echo $OTEL_SERVICE_NAME
Verify the OpenTelemetry initializer loads:
Add debug logging to your initializer:
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']}"
Verify network connectivity:
# For SigNoz Cloud
curl -v https://ingest.<region>.signoz.cloud:443/v1/traces
Why do OTLP exports fail with connection refused?
- VM: Verify the endpoint URL and that your firewall allows outbound HTTPS
- Kubernetes: Ensure the OTel Collector service is running and accessible
- Self-hosted: Confirm the collector is listening on the expected port
Why are some Rails requests not traced?
Check if the instrumentation gem is properly required:
# Verify instrumentations are loaded
puts OpenTelemetry.tracer_provider.tracer('test').class
Ensure the initializer runs before Rails fully starts by using config/initializers/ directory.
Why do I see duplicate spans?
This can happen if you have both opentelemetry-instrumentation-all and individual instrumentation gems. Use one or the other:
# 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'
Setup OpenTelemetry Collector (Optional)
What is the OpenTelemetry Collector?
Think of the OTel Collector as a middleman between your app and SigNoz. Instead of your application sending data directly to SigNoz, it sends everything to the Collector first, which then forwards it along.
Why use it?
- Cleaning up data — Filter out noisy traces you don't care about, or remove sensitive info before it leaves your servers.
- Keeping your app lightweight — Let the Collector handle batching, retries, and compression instead of your application code.
- Adding context automatically — The Collector can tag your data with useful info like which Kubernetes pod or cloud region it came from.
- Future flexibility — Want to send data to multiple backends later? The Collector makes that easy without changing your app.
See Switch from direct export to Collector for step-by-step instructions to convert your setup.
For more details, see Why use the OpenTelemetry Collector? and the Collector configuration guide.
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.