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.
# Gemfile
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all" # 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 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
Each request is one root server span named after its method and route, such as GET /orders/:id on Rails 7.1 and later.
pg, mysql2 and trilogy queries become child spans. pg and mysql2 obfuscate literal values in the query text by default.
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.
Net::HTTP and Faraday calls carry traceparent. An instrumented callee joins the trace and draws an edge on the service map.
Redis commands and template rendering show as spans inside the request that ran them.
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.
The Ruby trace SDK is stable. Its metrics and logs SDKs are still experimental, so this setup sends traces and nothing else.
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.
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.
The batch span processor restarts its export thread after a fork, so preload_app! and other forking servers need no on_worker_boot hook.
OTEL_TRACES_EXPORTER=console prints spans to stdout. OTEL_LOG_LEVEL=debug prints the SDK's export errors.
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.
Add the SDK, point your OTLP exporter at Maple, and traces arrive.
maple.dev: observability on OpenTelemetry