Ruby tracing installation

For the complete SDK reference, see the OpenTelemetry Ruby docs.

Add the SDK and OTLP exporter to your Gemfile:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'

Then run bundle install. The opentelemetry-exporter-otlp gem exports over OTLP HTTP/protobuf.

You'll need your PostHog project token to authenticate trace requests. This is the same token you use for capturing events with the PostHog SDK.

Important: Use your project token which starts with phc_. Do not use a personal API key (which starts with phx_).

You can find your project token in Project settings.

Set up the OpenTelemetry SDK to export spans to PostHog over OTLP HTTP.

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-service'
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'https://us.i.posthog.com/i/v1/traces',
        headers: { 'Authorization' => 'Bearer <ph_project_token>' }
      )
    )
  )
end

Alternatively, configure the exporter with environment variables and use a bare OpenTelemetry::SDK.configure:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.i.posthog.com/i/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <ph_project_token>"
OTEL_SERVICE_NAME="my-service"

Note: Pass the full /i/v1/traces path to the traces endpoint. Don't use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, which appends its own /v1/traces.

Wrap the operations you want to measure in spans, and attach attributes for context.

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

tracer.in_span('process-order') do |span|
  span.set_attribute('order.id', order_id)
  # ... do work ...
end

Once everything is configured, confirm spans are reaching PostHog:

1. Run your application and trigger the instrumented code
2. Open the PostHog Tracing interface
3. Confirm your spans and traces appear