Migrate Ruby OpenTelemetry APM

Overview

The OpenTelemetry Ruby SDK provides APIs for manual trace instrumentation and automatic instrumentation via the opentelemetry-instrumentation-all bundle, which covers many popular Ruby libraries. This page covers installing the SDK, setting up instrumentation, and configuring the OTLP exporter to send traces to Kloudfuse.

Install

Run this command to install the Ruby SDK, OTLP HTTP exporter, and all instrumentation libraries:

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

Set Up Instrumentation

Configure OpenTelemetry in an initializer that runs before your application code. For Rails, create config/initializers/opentelemetry.rb; for other frameworks, require this file at startup:

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

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-service'
  c.use_all   # enable all available instrumentation libraries
end
ruby

Create manual spans in your application logic:

tracer = OpenTelemetry.tracer_provider.tracer('my-service')

tracer.in_span('my-operation') do |span|
  span.set_attribute('key', 'value')
  # your work here
end
ruby

For full setup details, follow the OpenTelemetry documentation on Instrumentation.

Send to Kloudfuse

Configure the OTLP exporter by setting the following environment variables before starting your application:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<kloudfuse-hostname>/ingester/otlp"   (1)
export OTEL_EXPORTER_OTLP_HEADERS="Kf-Api-Key=<api-key>"                          (2)
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
1 Replace <kloudfuse-hostname> with your Kloudfuse cluster hostname.
2 Replace <api-key> with your Kloudfuse API key.

Instrumentation Libraries

OpenTelemetry Ruby supports automatic instrumentation for many popular libraries via the instrumentation bundle. See Configuring all instrumentation libraries for setup instructions.

Troubleshooting

No Traces Appear

Confirm that the OpenTelemetry initializer runs before Rack, Rails, or any other framework middleware is loaded. If OpenTelemetry::SDK.configure is called after the middleware stack is assembled, Rack and HTTP instrumentation will not be active. For Rails, ensure your initializer file is in config/initializers/ and not loaded lazily.

HTTP Requests Not Traced

If the opentelemetry-instrumentation-rack or opentelemetry-instrumentation-faraday gems are not in your bundle, those layers will not be instrumented. Verify that opentelemetry-instrumentation-all is installed, or add individual instrumentation gems explicitly.

Spans Created But Not Exported

If OTEL_EXPORTER_OTLP_ENDPOINT is not set, the SDK defaults to http://localhost:4318 and exports will silently fail if no collector is running there. Confirm the environment variable is set and accessible from the Ruby process at startup.

External References