SpitfireLoad Testing & Observabilityv1.1.0 · What's new

Version: 1.1.0This documentation is for Spitfire 1.1.0.

Connecting a Ruby service with OTel

Rails and Sinatra; traces. Values: Connecting services with OTel: overview.

Version table

Ruby opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all Framework
3.3 and later 1.13.1 0.37.0 0.100.0 Rails 7.1, 7.2, 8.x; Sinatra 2, 3, 4
3.2 1.10.0 0.32.0 0.91.0 Rails 7.0 – 8.x; Sinatra 2, 3, 4
3.1 and earlier not supported – – Upgrade to Ruby 3.3

Find your version: ruby --version

The commands say 1.13.1, 0.37.0, 0.100.0; for Ruby 3.2 write 1.10.0, 0.32.0, 0.91.0.

Metrics and logs: not sent (the Ruby metrics and logs SDKs are not stable). Server metrics: Collector.

Verified: 2026-11-04. Source: Ruby getting started, supported Ruby versions, RubyGems opentelemetry-sdk, RubyGems opentelemetry-exporter-otlp, RubyGems opentelemetry-instrumentation-all, Rails instrumentation (Rails versions).

What you need

  • Spitfire address https://<spitfire> and OTLP receiver token sfotlp_…
  • Service name <service-name>, version <service-version>, environment <environment>
  • The application folder (here /srv/app, where Gemfile is)

Linux (systemd)

  1. Add the gems:
bash
cd /srv/app && bundle add opentelemetry-sdk --version 1.13.1 && bundle add opentelemetry-exporter-otlp --version 0.37.0 && bundle add opentelemetry-instrumentation-all --version 0.100.0
  1. Rails: create /srv/app/config/initializers/opentelemetry.rb; Sinatra: create /srv/app/config/opentelemetry.rb. Paste:
ruby
# IS_OTEL_ENABLED=true: OTel on; any other value: off.
if ENV['IS_OTEL_ENABLED'] == 'true'
  require 'opentelemetry/sdk'
  require 'opentelemetry/exporter/otlp'
  require 'opentelemetry/instrumentation/all'
  OpenTelemetry::SDK.configure(&:use_all)
end
  1. Sinatra only: in app.rb, under require 'sinatra', add:
ruby
require_relative 'config/opentelemetry'
  1. Create the folder:
bash
sudo mkdir -p /etc/spitfire-otel
  1. Create /etc/spitfire-otel/<service-name>.env and paste:
bash
IS_OTEL_ENABLED=true
OTEL_SERVICE_NAME=<service-name>
OTEL_RESOURCE_ATTRIBUTES=service.version=<service-version>,deployment.environment=<environment>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=authorization=sfotlp_…
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
NO_PROXY=<spitfire>
#OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/spitfire-otel/ca.pem
  1. Restrict its permission:
bash
sudo chmod 600 /etc/spitfire-otel/<service-name>.env
  1. Give the environment file to the service (<unit>: its systemd unit):
bash
sudo mkdir -p /etc/systemd/system/<unit>.service.d && printf '[Service]\nEnvironmentFile=/etc/spitfire-otel/<service-name>.env\n' | sudo tee /etc/systemd/system/<unit>.service.d/otel.conf >/dev/null
  1. Restart:
bash
sudo systemctl daemon-reload && sudo systemctl restart <unit>

Docker

  1. Linux steps 2 and 3 in the image's source. In the Dockerfile, after bundle install:
dockerfile
RUN bundle add opentelemetry-sdk --version 1.13.1 && bundle add opentelemetry-exporter-otlp --version 0.37.0 && bundle add opentelemetry-instrumentation-all --version 0.100.0
  1. Save the environment file (Linux steps 4–6) on the Docker machine, then run:
bash
docker run -d --env-file /etc/spitfire-otel/<service-name>.env <image>
  1. After an environment file change, recreate the container:
bash
docker compose -f /srv/app/compose.yaml up -d --force-recreate <service>

Kubernetes

  1. Prepare the image as in the Docker section. Make the environment file a Secret:
bash
kubectl create secret generic <service-name>-otel --from-env-file=/etc/spitfire-otel/<service-name>.env --dry-run=client -o yaml | kubectl apply -f -
  1. In the Deployment, under the container:
yaml
envFrom:
  - secretRef:
      name: <service-name>-otel
  1. Restart:
bash
kubectl rollout restart deployment/<deployment>

Verify

  1. The gems load:
bash
cd /srv/app && IS_OTEL_ENABLED=true bundle exec ruby -e 'require "opentelemetry/sdk"; require "opentelemetry/exporter/otlp"; require "opentelemetry/instrumentation/all"; puts "OK"'
  1. Spitfire takes the token:
bash
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/traces -H 'Authorization: Bearer sfotlp_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200
  

 && echo OK

Framework: Rails

Rails Instrumentation Server span
7.0 – 8.x opentelemetry-instrumentation-rails (in instrumentation-all) ItemsController#show

Verified: 2026-11-04. Source: instrumentation-rails.

  1. Set up as in your environment's section above; file config/initializers/opentelemetry.rb.
  2. Check the Rails instrumentation is installed:
bash
cd /srv/app && IS_OTEL_ENABLED=true bundle exec rails runner 'puts OpenTelemetry::Instrumentation::Rails::Instrumentation.instance.installed? ? "OK" : "NO"' | grep -q '^OK
  

 && echo OK

Framework: Sinatra

Sinatra Instrumentation Server span
2, 3, 4 opentelemetry-instrumentation-sinatra (in instrumentation-all) GET /items/:id

Verified: 2026-11-04. Source: instrumentation-sinatra.

  1. Set up as in your environment's section above; file config/opentelemetry.rb, plus the require_relative line in app.rb.
  2. Check the Sinatra instrumentation is installed:
bash
cd /srv/app && IS_OTEL_ENABLED=true bundle exec ruby -e 'require "opentelemetry/instrumentation/sinatra"' && echo OK

Turning off and removing

  1. Turn off: in the environment file write IS_OTEL_ENABLED=false, then restart (Linux step 8, docker compose … --force-recreate, or kubectl rollout restart).
  2. Remove:
bash
cd /srv/app && bundle remove opentelemetry-instrumentation-all opentelemetry-exporter-otlp opentelemetry-sdk && rm -f config/initializers/opentelemetry.rb config/opentelemetry.rb

Common problems

Symptom Fix
Could not find compatible versions Write your Ruby band's versions
No spans IS_OTEL_ENABLED=true in the environment file; restart
Verify step 2 prints nothing Address or token: Verifying
Sinatra: no spans require_relative 'config/opentelemetry' must come after require 'sinatra'