Ruby SDK

Requirements: Ruby ≥ 3.0

Installation

Add to your Gemfile:

Gemfile

gem "tracelit"

Then run:

bundle install

Quick start

Rails
Sinatra / Rack

Create an initializer

config/initializers/tracelit.rb

Tracelit.configure do |config|
  config.api_key      = ENV["TRACELIT_API_KEY"]   # required
  config.service_name = "payments-api"             # required
  config.environment  = ENV["RAILS_ENV"]
  config.sample_rate  = 1.0
end

You're done

The Railtie picks up the configuration automatically and calls Tracelit.start! at boot. No further changes needed.

Require and configure

app.rb

require "tracelit"

Tracelit.configure do |config|
  config.api_key      = ENV["TRACELIT_API_KEY"]
  config.service_name = "my-sinatra-app"
  config.environment  = ENV["RACK_ENV"]
end

Tracelit.start!  # must be called explicitly outside Rails

Configuration reference

All options can be set in the configure block or via environment variables.

Option	Env variable	Default	Description
`api_key`	`TRACELIT_API_KEY`	`nil`	Required. Your Tracelit ingest API key
`service_name`	`TRACELIT_SERVICE_NAME`	Rails app name	Required. Service name shown in Tracelit
`environment`	`TRACELIT_ENVIRONMENT`	`"production"`	Deployment environment tag
`endpoint`	`TRACELIT_ENDPOINT`	`https://ingest.tracelit.app`	Override only when self-hosting
`sample_rate`	`TRACELIT_SAMPLE_RATE`	`1.0`	Head-based sampling ratio `0.0`–`1.0`. Errors always export.
`enabled`	`TRACELIT_ENABLED`	`true`	Set `false` to disable all telemetry
`resource_attributes`	—	`{}`	Extra key/value pairs on every span, metric, and log

Custom resource attributes

Tracelit.configure do |config|
  config.api_key      = ENV["TRACELIT_API_KEY"]
  config.service_name = "orders-api"
  config.resource_attributes = {
    "deployment.region" => "us-east-1",
    "team"              => "platform",
  }
end

Tracing

Manual spans

Tracelit.tracer is an OpenTelemetry::Trace::Tracer and supports the full OpenTelemetry Ruby API.

Tracelit.tracer.in_span("process_payment") do |span|
  span.set_attribute("payment.id",       payment.id.to_s)
  span.set_attribute("payment.amount",   amount)
  span.set_attribute("payment.currency", currency)

  result = process(payment)

  span.set_attribute("payment.status", result.status)
  result
end

Nesting spans

Tracelit.tracer.in_span("checkout") do |checkout_span|
  checkout_span.set_attribute("cart.items", cart.size)

  Tracelit.tracer.in_span("validate-inventory") do |inv_span|
    validate_inventory!(cart)
  end

  Tracelit.tracer.in_span("charge-card") do |pay_span|
    pay_span.set_attribute("payment.gateway", "stripe")
    charge_card!(cart, payment_method)
  end
end

Recording errors

Tracelit.tracer.in_span("risky-operation") do |span|
  begin
    risky!
  rescue => e
    span.record_exception(e)
    span.status = OpenTelemetry::Trace::Status.error(e.message)
    raise
  end
end

Automatic instrumentation

The SDK enables every instrumentation gem bundled in opentelemetry-instrumentation-all:

Library	What is captured
Rails / Action Pack	HTTP request traces, controller and action attributes
Active Record	SQL query traces with sanitised statement text
Action View	Template render times
Rack	Low-level HTTP middleware spans
Net::HTTP	Outbound HTTP call traces
Faraday	Outbound HTTP call traces
Redis	Cache command traces
Sidekiq	Job enqueue and execute traces
Bunny	AMQP publish/subscribe traces
gRPC	Client and server RPC traces

Additional libraries (Mongo, pg, mysql2, Kafka, etc.) are also instrumented when their gems are present.

Metrics

Automatic metrics

The SDK emits the following metrics out of the box — no configuration required:

Metric	Type	Interval	Description
`http.server.request.count`	Counter	per request	Total HTTP requests, tagged by `http.route`, `http.method`, `http.status_code`
`http.server.request.duration`	Histogram (ms)	per request	End-to-end request duration
`http.server.error.count`	Counter	per request	5xx responses only
`db.query.duration`	Histogram (ms)	per request	Total ActiveRecord time per request
`sidekiq.job.count`	Counter	per job	Jobs processed, tagged by `sidekiq.job.class`, `sidekiq.queue`, `sidekiq.status`
`sidekiq.job.duration`	Histogram (ms)	per job	Job execution time
`sidekiq.job.error.count`	Counter	per job	Jobs that raised an error
`db.connection_pool.size`	Gauge	30 s	Maximum connections in the pool
`db.connection_pool.busy`	Gauge	30 s	Connections currently checked out
`db.connection_pool.idle`	Gauge	30 s	Connections available for checkout
`db.connection_pool.waiting`	Gauge	30 s	Threads waiting for a connection
`process.memory.rss`	Gauge (MB)	60 s	Process resident set size
`process.runtime.cpu.usage`	Gauge (%)	30 s	Process CPU utilisation

Sidekiq and ActiveRecord metrics are only installed when those libraries are present. All pollers are fork-safe — they restart automatically inside each Puma cluster worker.

Manual metrics

# Counter — increment on each event
orders = Tracelit.metrics.counter("orders.placed", description: "Total orders placed")
orders.add(1, attributes: { "currency" => "USD" })

# Histogram — record a measured value
latency = Tracelit.metrics.histogram("payment.duration", unit: "ms")
latency.record(elapsed_ms, attributes: { "gateway" => "stripe" })

# Gauge — record a point-in-time value
depth = Tracelit.metrics.gauge("queue.depth", description: "Current queue depth")
depth.record(queue.size, attributes: { "queue" => "default" })

Log forwarding (Rails)

When Rails is present, Tracelit.start! installs a broadcast target on Rails.logger. Every Rails.logger call is forwarded to the OTel LoggerProvider and exported to the Tracelit logs table via OTLP.

Original logger output is preserved — nothing changes for your existing log pipeline
Log records are automatically correlated with the active trace via trace_id and span_id

# This works exactly as before — no changes needed
Rails.logger.info("Order #{order.id} created", { amount: order.total })
# ↑ Automatically includes trace_id + span_id in Tracelit

Sampling and error guarantee

config.sample_rate = 0.1   # keep 10% of traces

Error spans are always exported, even when the parent trace is outside the sample ratio. The SDK uses a custom ErrorAlwaysOnSampler + ErrorSpanProcessor pair to guarantee this — no configuration required.

Disabling in specific environments

Tests

# config/initializers/tracelit.rb
Tracelit.configure do |config|
  config.api_key      = ENV["TRACELIT_API_KEY"]
  config.service_name = "my-app"
  config.enabled      = ENV["TRACELIT_ENABLED"] != "false"
end

# Run tests with telemetry off
TRACELIT_ENABLED=false bundle exec rspec

# Or set permanently in config/environments/test.rb or .env.test
TRACELIT_ENABLED=false

Rails console

By default the SDK initialises during rails console, printing OTel instrumentation startup lines before your prompt. Suppress this with:

# config/initializers/tracelit.rb
Tracelit.configure do |config|
  config.api_key      = ENV["TRACELIT_API_KEY"]
  config.service_name = ENV["TRACELIT_SERVICE_NAME"]
  config.environment  = ENV["TRACELIT_ENVIRONMENT"]
  config.enabled      = !defined?(Rails::Console)
end

Rails::Console is defined only when the process was started via rails console, so this has no effect on your server or background workers.

Commit SHA tracking

The SDK automatically attaches the current commit SHA as service.commit_sha on every span, metric, and log. It resolves the SHA from common CI/CD environment variables with no configuration needed:

Platform	Environment variable
GitHub Actions	`GITHUB_SHA`
Heroku	`HEROKU_SLUG_COMMIT` / `SOURCE_VERSION`
Render	`RENDER_GIT_COMMIT`
Fly.io	`FLY_APP_VERSION`
Railway	`RAILWAY_GIT_COMMIT_SHA`
Generic CI	`COMMIT_SHA` / `GIT_COMMIT_SHA` / `GIT_COMMIT`
Local dev	`git rev-parse HEAD` (subprocess fallback)

No action required — if any of the above is set at boot time the SHA is picked up automatically.

GitHub

Source code and issue tracker: github.com/Tracelit-AI/tracelit-ruby

Getting Started

Core Features

Agentic Process

Integrations

Installation

Quick start

Configuration reference

Custom resource attributes

Tracing

Manual spans

Nesting spans

Recording errors

Automatic instrumentation

Metrics

Automatic metrics

Manual metrics

Log forwarding (Rails)

Sampling and error guarantee

Disabling in specific environments

Tests

Rails console

Commit SHA tracking

GitHub

​Installation

​Quick start

​Configuration reference

​Custom resource attributes

​Tracing

​Manual spans

​Nesting spans

​Recording errors

​Automatic instrumentation

​Metrics

​Automatic metrics

​Manual metrics

​Log forwarding (Rails)

​Sampling and error guarantee

​Disabling in specific environments

​Tests

​Rails console

​Commit SHA tracking

​GitHub

Installation

Quick start

Configuration reference

Custom resource attributes

Tracing

Manual spans

Nesting spans

Recording errors

Automatic instrumentation

Metrics

Automatic metrics

Manual metrics

Log forwarding (Rails)

Sampling and error guarantee

Disabling in specific environments

Tests

Rails console

Commit SHA tracking

GitHub