OpenTelemetry tracing for Ruby on Rails

Three gems and one initializer. opentelemetry-instrumentation-all turns on tracing for Rails, Active Record, Sidekiq, Net::HTTP and the other libraries your app loads, and the SDK exports the spans to Maple.

GET /orders/:id 5 spans · 92ms
DurationStatus
/orders/:idstore-web
92.0msOk
SELECT store_production
8.0msOk
redis GET
2.0msOk
app/views/orders/show.html.erb
41.0msOk
default publish
4.0msOk

Example: a Rails request that enqueues a Sidekiq job

Quick start

Set up Ruby

1

Add the gems, then run bundle install

ruby
# Gemfile
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"
2

Create an initializer

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

# Runs in every Rails process: Puma, the console, runners and Sidekiq
OpenTelemetry::SDK.configure do |c|
  c.use_all
end
3

Point the exporter at Maple, with a service name per process

bash
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_INGEST_KEY"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"

OTEL_SERVICE_NAME=store-web bin/rails server
OTEL_SERVICE_NAME=store-worker bundle exec sidekiq

This is the short path. The full Ruby guide covers the rest.

Organization in the EU region? Send to https://ingest.eu.maple.dev instead of https://ingest.maple.dev. An ingest key only works in its own region.

What you get

What a Rails app sends to Maple

Rails requests

Each request is one root server span named after its method and route, such as GET /orders/:id on Rails 7.1 and later.

Active Record and SQL

pg, mysql2 and trilogy queries become child spans. pg and mysql2 obfuscate literal values in the query text by default.

Sidekiq jobs

Each enqueue is a producer span and each run a consumer span. The worker process runs the same initializer, so it needs no setup of its own.

Outgoing HTTP

Net::HTTP and Faraday calls carry traceparent. An instrumented callee joins the trace and draws an edge on the service map.

Redis and Action View

Redis commands and template rendering show as spans inside the request that ran them.

Your own spans

Wrap your own code in in_span. An exception raised inside the block is recorded on the span, marks it as an error and is re-raised.

What is different in Ruby

Traces only, for now

The Ruby trace SDK is stable. Its metrics and logs SDKs are still experimental, so this setup sends traces and nothing else.

HTTP, never gRPC

opentelemetry-exporter-otlp speaks OTLP over HTTP only. If OTEL_EXPORTER_OTLP_PROTOCOL is grpc, often inherited from a shared environment, the SDK logs a warning and exports nothing.

One trace per job, if you want it

By default a job starts its own trace, linked to the request that enqueued it. Pass { "OpenTelemetry::Instrumentation::Sidekiq" => { propagation_style: :child } } to use_all to put both in one trace. Keep the default for jobs that enqueue many others.

Puma cluster mode needs nothing

The batch span processor restarts its export thread after a fork, so preload_app! and other forking servers need no on_worker_boot hook.

See spans before you send them

OTEL_TRACES_EXPORTER=console prints spans to stdout. OTEL_LOG_LEVEL=debug prints the SDK's export errors.

A missing gem fails quietly

If the log says to add opentelemetry-exporter-otlp to your Gemfile, the exporter is not in the bundle and no span leaves the process.

통합

다른 통합

오늘 첫 트레이스를 확인하세요.

SDK를 추가하고 OTLP 익스포터를 Maple로 향하게 하면 트레이스가 도착합니다.

maple.dev: OpenTelemetry 위의 옵저버빌리티