Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tracelit.io/llms.txt

Use this file to discover all available pages before exploring further.

Requirements: Ruby ≥ 3.0

​
Installation

Add to your Gemfile:
Gemfile
gem "tracelit"
Then run: 
bundle install

​
Quick start

1

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
2

You're done

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

​
Configuration reference

All options can be set in the configure block or via environment variables.
OptionEnv variableDefaultDescription
api_keyTRACELIT_API_KEYnilRequired. Your Tracelit ingest API key
service_nameTRACELIT_SERVICE_NAMERails app nameRequired. Service name shown in Tracelit
environmentTRACELIT_ENVIRONMENT"production"Deployment environment tag
endpointTRACELIT_ENDPOINThttps://ingest.tracelit.appOverride only when self-hosting
sample_rateTRACELIT_SAMPLE_RATE1.0Head-based sampling ratio 0.0–1.0. Errors always export.
enabledTRACELIT_ENABLEDtrueSet 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:
LibraryWhat is captured
Rails / Action PackHTTP request traces, controller and action attributes
Active RecordSQL query traces with sanitised statement text
Action ViewTemplate render times
RackLow-level HTTP middleware spans
Net::HTTPOutbound HTTP call traces
FaradayOutbound HTTP call traces
RedisCache command traces
SidekiqJob enqueue and execute traces
BunnyAMQP publish/subscribe traces
gRPCClient and server RPC traces
Additional libraries (Mongo, pg, mysql2, Kafka, etc.) are also instrumented when their gems are present.

​
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 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

​
GitHub

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