tracelit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58eb691b0dfacebc7072a0ee10ebc4fb88ddc5074c659211a689532bf2e86f3b
+  data.tar.gz: 9a73dad4b506173c24f6e64a17c227812a0ab90651ef3a08e493ab9a68c602e1
+SHA512:
+  metadata.gz: 7ca34cc0206da44b31ceb865848ec08ef39f015764ae7f1f20dcf6d2b9af78820de537f6994ea48a224415350878ea9c206a54f21dd434cb37146451a04a06ba
+  data.tar.gz: 999c495a4c363af34e4bdd1671d66611c42124040f2e20172040590dbb5e6a715f9123e4550a29c2378c77d5275cede91fdc8dd46ca1830c1eabfa2b6b92eac3

data/README.md

@@ -0,0 +1,361 @@
+# Tracelit Ruby SDK
+
+Official Ruby SDK for [Tracelit](https://tracelit.io) — drop-in OpenTelemetry instrumentation for Rails, Sinatra, and Rack apps. Sends traces, metrics, and logs to the Tracelit ingest API via OTLP/HTTP.
+
+**Requirements:** Ruby >= 3.0
+
+---
+
+## Set up with AI
+
+Copy the prompt below and paste it into Cursor, Claude, ChatGPT, or any AI assistant. It contains everything the AI needs to fully integrate Tracelit into your app — gem, initializer, manual spans, custom metrics, and test guard.
+
+````
+You are integrating the Tracelit Ruby SDK into this codebase.
+
+## What Tracelit does
+Tracelit is a drop-in OpenTelemetry SDK that sends traces, metrics, and logs
+to https://tracelit.io via OTLP/HTTP. It auto-instruments Rails, Sidekiq,
+ActiveRecord, Redis, Faraday, Net::HTTP, and more with zero code changes.
+
+## Steps
+
+### 1. Add the gem
+In Gemfile add:
+  gem "tracelit"
+Then run: bundle install
+
+### 2. Create the initializer
+Create config/initializers/tracelit.rb with this content
+(replace MY_SERVICE_NAME with the actual name of this service):
+
+  Tracelit.configure do |config|
+    config.api_key      = ENV["TRACELIT_API_KEY"]
+    config.service_name = "MY_SERVICE_NAME"
+    config.environment  = ENV.fetch("RAILS_ENV", "production")
+    config.sample_rate  = 1.0
+    config.enabled      = ENV["TRACELIT_ENABLED"] != "false"
+  end
+
+For Sinatra/Rack apps also add Tracelit.start! after the configure block.
+For Rails, the Railtie calls start! automatically — no extra line needed.
+
+### 3. Disable in tests
+In config/environments/test.rb (or .env.test) add:
+  TRACELIT_ENABLED=false
+
+### 4. Add manual spans (optional)
+Wrap any important operation with a custom span:
+
+  Tracelit.tracer.in_span("describe_the_operation") do |span|
+    span.set_attribute("relevant.attribute", value.to_s)
+    do_the_work
+  end
+
+### 5. Add custom metrics (optional)
+Use counters, histograms, or gauges for business-level signals:
+
+  # Counter — increment by 1 each time an event occurs
+  counter = Tracelit.metrics.counter("my.event.count",
+    description: "...", unit: "{events}")
+  counter.add(1, attributes: { "key" => "value" })
+
+  # Histogram — record a measured value (latency, size, etc.)
+  histogram = Tracelit.metrics.histogram("my.operation.duration",
+    description: "...", unit: "ms")
+  histogram.record(elapsed_ms, attributes: { "key" => "value" })
+
+  # Gauge — record a current level (queue depth, pool size, etc.)
+  gauge = Tracelit.metrics.gauge("my.queue.depth",
+    description: "...", unit: "{items}")
+  gauge.record(current_depth, attributes: { "queue" => "default" })
+
+## What you get automatically (no code required)
+- Traces for every HTTP request, SQL query, Redis call, Sidekiq job, etc.
+- Metrics: http.server.request.count/duration, http.server.error.count,
+  db.query.duration, sidekiq.job.count/duration/error.count,
+  db.connection_pool.size/busy/idle/waiting, process.memory.rss
+- Rails.logger lines forwarded to Tracelit logs, correlated to the active trace
+- Error spans always exported even when the trace is outside the sample ratio
+
+## Configuration reference
+| Option             | Env var                  | Default                        |
+|--------------------|--------------------------|--------------------------------|
+| api_key            | TRACELIT_API_KEY         | nil (required)                 |
+| service_name       | TRACELIT_SERVICE_NAME    | Rails app name (required)      |
+| environment        | TRACELIT_ENVIRONMENT     | "production"                   |
+| endpoint           | TRACELIT_ENDPOINT        | https://ingest.tracelit.app    |
+| sample_rate        | TRACELIT_SAMPLE_RATE     | 1.0                            |
+| enabled            | TRACELIT_ENABLED         | true                           |
+| resource_attributes| —                        | {} (extra span/metric tags)    |
+````
+
+---
+
+## Installation
+
+Add to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem "tracelit"
+```
+
+---
+
+## Setup
+
+### Rails
+
+Create `config/initializers/tracelit.rb`:
+
+```ruby
+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
+```
+
+That is all. The Railtie picks up the configuration automatically and calls `Tracelit.start!` at boot — no further changes needed.
+
+### Sinatra / Rack
+
+```ruby
+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.** Name of this service as it appears in Tracelit. Falls back to the Rails application module name when inside Rails, or `"unknown-service"` otherwise. |
+| `environment` | `TRACELIT_ENVIRONMENT` | `"production"` | Deployment environment tag — e.g. `production`, `staging`, `development`. |
+| `endpoint` | `TRACELIT_ENDPOINT` | `https://ingest.tracelit.app` | Base URL of the Tracelit ingest API. Override only when self-hosting. |
+| `sample_rate` | `TRACELIT_SAMPLE_RATE` | `1.0` | Head-based trace sampling ratio between `0.0` and `1.0`. `1.0` keeps every trace; `0.1` keeps 10%. **Errors are always exported regardless of this setting.** |
+| `enabled` | `TRACELIT_ENABLED` | `true` | Set to `false` (or `TRACELIT_ENABLED=false`) to disable all telemetry without removing the gem — useful in test environments. |
+| `resource_attributes` | — | `{}` | Extra key/value pairs appended to every span, metric, and log record as resource attributes. |
+
+### Adding custom resource attributes
+
+```ruby
+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
+```
+
+---
+
+## Manual trace instrumentation
+
+Use `Tracelit.tracer` to create custom spans around any block of work:
+
+```ruby
+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
+```
+
+The tracer is an `OpenTelemetry::Trace::Tracer` and supports the full [OpenTelemetry Ruby API](https://opentelemetry.io/docs/languages/ruby/api/).
+
+---
+
+## Manual metrics instrumentation
+
+Access the metrics interface via `Tracelit.metrics` (an alias for `Tracelit::Metrics`):
+
+### Counter
+
+Counts discrete events. Use for request counts, job completions, errors, etc.
+
+```ruby
+counter = Tracelit.metrics.counter(
+  "orders.placed",
+  description: "Total orders placed",
+  unit: "{orders}"
+)
+
+counter.add(1, attributes: { "currency" => "USD", "channel" => "web" })
+```
+
+### Histogram
+
+Records distributions of values. Use for durations, payload sizes, queue depths, etc.
+
+```ruby
+histogram = Tracelit.metrics.histogram(
+  "external.api.duration",
+  description: "External API call duration",
+  unit: "ms"
+)
+
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+call_external_api
+elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+
+histogram.record(elapsed_ms, attributes: { "service" => "stripe" })
+```
+
+### Gauge
+
+Records a point-in-time value. Use for pool sizes, queue lengths, cache hit rates, etc.
+
+```ruby
+gauge = Tracelit.metrics.gauge(
+  "job_queue.depth",
+  description: "Number of pending background jobs",
+  unit: "{jobs}"
+)
+
+gauge.record(JobQueue.pending_count, attributes: { "queue" => "default" })
+```
+
+---
+
+## Automatic instrumentation
+
+The SDK enables every instrumentation gem bundled in `opentelemetry-instrumentation-all`, including:
+
+| 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.
+
+---
+
+## Automatic metrics collection
+
+Once `Tracelit.start!` has been called, the following metrics are collected with no additional configuration:
+
+### HTTP server metrics (Rails)
+
+Emitted per request via `ActiveSupport::Notifications`:
+
+| Metric | Type | Description |
+|---|---|---|
+| `http.server.request.count` | Counter | Total HTTP requests processed |
+| `http.server.request.duration` | Histogram | Request duration in milliseconds |
+| `http.server.error.count` | Counter | Total 5xx responses |
+| `db.query.duration` | Histogram | ActiveRecord time per request in milliseconds |
+
+Attributes on all HTTP metrics: `http.method`, `http.route`, `http.status_code`, `controller`, `action`.
+
+### Sidekiq job metrics
+
+Emitted per job execution via server middleware:
+
+| Metric | Type | Description |
+|---|---|---|
+| `sidekiq.job.count` | Counter | Total jobs processed |
+| `sidekiq.job.duration` | Histogram | Job execution duration in milliseconds |
+| `sidekiq.job.error.count` | Counter | Total jobs that raised an error |
+
+Attributes: `sidekiq.job.class`, `sidekiq.queue`, `sidekiq.status` (`success` or `error`).
+
+### Database connection pool metrics (ActiveRecord)
+
+Polled every 30 seconds on a background thread:
+
+| Metric | Type | Description |
+|---|---|---|
+| `db.connection_pool.size` | Gauge | Maximum connections in the pool |
+| `db.connection_pool.busy` | Gauge | Connections currently checked out |
+| `db.connection_pool.idle` | Gauge | Connections available for checkout |
+| `db.connection_pool.waiting` | Gauge | Threads waiting for a connection |
+
+### Process memory
+
+Polled every 60 seconds:
+
+| Metric | Type | Description |
+|---|---|---|
+| `process.memory.rss` | Gauge | Process RSS memory in megabytes |
+
+---
+
+## 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. The 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`.
+
+---
+
+## Sampling and error guarantee
+
+Set `config.sample_rate` below `1.0` to reduce trace volume in high-traffic environments:
+
+```ruby
+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
+
+```ruby
+# 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
+```
+
+Then in your test environment:
+
+```bash
+TRACELIT_ENABLED=false bundle exec rspec
+```
+
+Or set it permanently in `config/environments/test.rb` / `.env.test`:
+
+```
+TRACELIT_ENABLED=false
+```
+
+---
+
+## Running the SDK's own tests
+
+```bash
+bundle install
+bundle exec rspec
+```

data/lib/tracelit/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Tracelit
+  class Configuration
+    # Required
+    attr_accessor :api_key
+
+    # The name of this service as it will appear in Tracelit.
+    # Defaults to the Rails app name if Rails is present.
+    attr_accessor :service_name
+
+    # Environment tag — production, staging, development, etc.
+    attr_accessor :environment
+
+    # Full URL of the Tracelit ingest endpoint.
+    # Override only if self-hosting.
+    attr_accessor :endpoint
+
+    # Head-based sampling rate (0.0–1.0). Default: 1.0 (keep all traces).
+    # Set to 0.1 to keep 10% of traces. Errors are always kept regardless.
+    attr_accessor :sample_rate
+
+    # Set false to disable all telemetry without removing the gem.
+    # Useful for test environments.
+    attr_accessor :enabled
+
+    # Additional resource attributes appended to every span and log.
+    # Hash of string keys and string values.
+    attr_accessor :resource_attributes
+
+    def initialize
+      @api_key            = ENV["TRACELIT_API_KEY"]
+      @service_name       = ENV["TRACELIT_SERVICE_NAME"]
+      @environment        = ENV["TRACELIT_ENVIRONMENT"] || "production"
+      @endpoint           = ENV["TRACELIT_ENDPOINT"]    || "https://ingest.tracelit.app"
+      @sample_rate        = (ENV["TRACELIT_SAMPLE_RATE"] || "1.0").to_f
+      @enabled            = ENV["TRACELIT_ENABLED"] != "false"
+      @resource_attributes = {}
+    end
+
+    def validate!
+      raise ArgumentError, "Tracelit.config.api_key is required" if api_key.nil? || api_key.empty?
+      raise ArgumentError, "Tracelit.config.service_name is required" if service_name.nil? || service_name.empty?
+      raise ArgumentError, "sample_rate must be between 0.0 and 1.0" unless sample_rate.between?(0.0, 1.0)
+    end
+
+    # Infer service name from Rails application if not explicitly set.
+    def resolved_service_name
+      return service_name if service_name && !service_name.empty?
+      return ::Rails.application.class.module_parent_name.underscore if defined?(::Rails)
+      "unknown-service"
+    end
+  end
+end

data/lib/tracelit/error_always_on_sampler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tracelit
+  # ErrorAlwaysOnSampler wraps a ratio-based sampler but upgrades DROP
+  # decisions to RECORD_ONLY. This ensures span processors (including
+  # ErrorSpanProcessor) fire on_end for ALL spans, even those outside
+  # the sampling ratio.
+  #
+  # Without this, TraceIdRatioBased(0.0) returns DROP, which causes the
+  # SDK to create NonRecordingSpans that bypass the processor pipeline
+  # entirely — so ErrorSpanProcessor.on_end is never called.
+  #
+  # With RECORD_ONLY:
+  # - Real spans are created and all processors fire
+  # - BatchSpanProcessor ignores them (checks trace_flags.sampled? == false)
+  # - ErrorSpanProcessor sees them and exports any that end in ERROR
+  class ErrorAlwaysOnSampler
+    Decision = OpenTelemetry::SDK::Trace::Samplers::Decision
+    Result   = OpenTelemetry::SDK::Trace::Samplers::Result
+
+    def initialize(rate)
+      @inner = OpenTelemetry::SDK::Trace::Samplers.trace_id_ratio_based(rate)
+    end
+
+    def should_sample?(trace_id:, parent_context:, links:, name:, kind:, attributes:)
+      result = @inner.should_sample?(
+        trace_id: trace_id,
+        parent_context: parent_context,
+        links: links,
+        name: name,
+        kind: kind,
+        attributes: attributes
+      )
+
+      if result.recording?
+        result
+      else
+        # Upgrade DROP → RECORD_ONLY so processor pipeline fires
+        Result.new(decision: Decision::RECORD_ONLY, tracestate: result.tracestate)
+      end
+    end
+
+    def description
+      "ErrorAlwaysOnSampler{#{@inner.description}}"
+    end
+  end
+end

data/lib/tracelit/error_span_processor.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tracelit
+  # ErrorSpanProcessor ensures error spans are always exported
+  # regardless of the sampling decision made at span creation time.
+  #
+  # How it works:
+  # - ErrorAlwaysOnSampler returns RECORD_ONLY (not DROP) for unsampled spans,
+  #   which ensures this processor's on_finish is called for every span
+  # - On span finish, if the span has status ERROR, this processor forces it
+  #   through the exporter directly, bypassing the BatchSpanProcessor
+  # - BatchSpanProcessor ignores RECORD_ONLY spans (trace_flags.sampled? false)
+  #   so there is no double-export for sampled error spans
+  #
+  # NOTE: opentelemetry-sdk 1.x uses on_finish (not on_end) as the hook name.
+  class ErrorSpanProcessor
+    def initialize(exporter)
+      @exporter = exporter
+    end
+
+    def on_start(span, parent_context)
+      # nothing to do at start
+    end
+
+    def on_finish(span)
+      # Skip spans that are not in error — only intervene for errors
+      return if span.status.ok?
+
+      # Skip spans that were fully sampled — BatchSpanProcessor handles those.
+      # This prevents double-export of error spans on traces that were sampled.
+      return if span.context.trace_flags.sampled?
+
+      # Force-export this error span regardless of sampling decision
+      @exporter.export([span.to_span_data])
+    rescue StandardError
+      # Never let processor errors propagate to the application
+    end
+
+    def force_flush(timeout: nil)
+      @exporter.force_flush(timeout: timeout)
+    end
+
+    def shutdown(timeout: nil)
+      # Do not shut down the shared exporter here —
+      # the BatchSpanProcessor owns its lifecycle
+    end
+  end
+end

data/lib/tracelit/instrumentation.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+require "opentelemetry/instrumentation/all"
+require "opentelemetry-logs-sdk"
+require "opentelemetry/exporter/otlp_logs"
+require_relative "error_span_processor"
+require_relative "error_always_on_sampler"
+require_relative "rails_logger_bridge"
+require_relative "metrics"
+
+module Tracelit
+  module Instrumentation
+    # Sets up the OpenTelemetry SDK with the Tracelit OTLP exporter.
+    # Called once at application boot. Idempotent — safe to call multiple times.
+    def self.setup(config)
+      return if @configured
+      return unless config.enabled
+
+      config.validate!
+
+      OpenTelemetry::SDK.configure do |otel|
+        # Resource attributes identify this service in Tracelit.
+        # These populate the `resource` Map column on every telemetry row.
+        otel.resource = OpenTelemetry::SDK::Resources::Resource.create(
+          {
+            OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME    => config.resolved_service_name,
+            OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => config.environment,
+            "telemetry.sdk.language" => "ruby",
+            "telemetry.sdk.name"     => detect_framework,
+            "telemetry.sdk.version"  => Tracelit::VERSION,
+          }.merge(config.resource_attributes)
+        )
+
+        # Build the OTLP exporter once — shared by both processors
+        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+          endpoint: "#{config.endpoint}/v1/traces",
+          headers: {
+            "Authorization"  => "Bearer #{config.api_key}",
+            "X-Service-Name" => config.resolved_service_name,
+            "X-Environment"  => config.environment,
+          }
+        )
+
+        # Primary processor: batches and exports sampled spans
+        otel.add_span_processor(
+          OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+        )
+
+        # Error processor: always exports error spans regardless of
+        # sampling decision — fires on_finish after status is known
+        otel.add_span_processor(
+          Tracelit::ErrorSpanProcessor.new(exporter)
+        )
+
+        # Auto-instrumentation: instruments Rails, Rack, ActiveRecord,
+        # Action View, Net::HTTP, Faraday, Redis, Sidekiq, and more.
+        # use_all() enables every installed instrumentation gem.
+        otel.use_all
+      end
+
+      # Set sampler after configure — Configurator does not expose
+      # sampler= in OTel SDK 1.x, must be set on the provider directly.
+      # Skip at 1.0: the default AlwaysOn sampler is correct and we do not touch it.
+      if config.sample_rate < 1.0
+        OpenTelemetry.tracer_provider.sampler = error_always_on_sampler(config.sample_rate)
+      end
+
+      @configured = true
+      setup_logs(config)
+      Tracelit::Metrics.setup(config)
+    end
+
+    def self.reset!
+      @configured = false
+    end
+
+    private
+
+    # Detects the web framework in use for the telemetry.sdk.name attribute.
+    # This value appears as the `framework` column in the services table.
+    def self.detect_framework
+      return "rails"   if defined?(::Rails)
+      return "sinatra" if defined?(::Sinatra)
+      return "rack"    if defined?(::Rack)
+      "ruby"
+    end
+
+    # Returns an ErrorAlwaysOnSampler wrapped in ParentBased so child spans
+    # honour the parent's sampling decision. ErrorAlwaysOnSampler upgrades
+    # DROP → RECORD_ONLY so that ErrorSpanProcessor.on_finish fires for all spans,
+    # allowing error spans to be exported even outside the sampling ratio.
+    def self.error_always_on_sampler(rate)
+      OpenTelemetry::SDK::Trace::Samplers.parent_based(
+        root: Tracelit::ErrorAlwaysOnSampler.new(rate)
+      )
+    end
+
+    # Sets up the OTel Logs SDK: creates a LoggerProvider, attaches a
+    # BatchLogRecordProcessor with an OTLP/HTTP exporter, registers it
+    # globally, and installs the Rails.logger bridge.
+    def self.setup_logs(config)
+      logs_exporter = OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+        endpoint: "#{config.endpoint}/v1/logs",
+        headers: {
+          "Authorization"  => "Bearer #{config.api_key}",
+          "X-Service-Name" => config.resolved_service_name,
+          "X-Environment"  => config.environment,
+        }
+      )
+
+      logger_provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(
+        resource: OpenTelemetry.tracer_provider.resource
+      )
+
+      logger_provider.add_log_record_processor(
+        OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(logs_exporter)
+      )
+
+      OpenTelemetry.logger_provider = logger_provider
+
+      # Install the Rails.logger → OTel bridge after the provider is ready.
+      # Called here (after Rails boot) so Rails.logger is already initialised.
+      RailsLoggerBridge.install(logger_provider)
+    rescue StandardError => e
+      OpenTelemetry.logger.warn("Tracelit: failed to set up logs: #{e.message}")
+    end
+  end
+end

data/lib/tracelit/metrics.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "opentelemetry/metrics"
+require "opentelemetry-metrics-sdk"
+require "opentelemetry/exporter/otlp_metrics"
+
+module Tracelit
+  module Metrics
+    # Sets up the OpenTelemetry MeterProvider with OTLP exporter.
+    # Called once from Instrumentation.setup after trace setup.
+    def self.setup(config)
+      # Force delta temporality for all instruments. The SDK aggregation classes
+      # (Sum, ExplicitBucketHistogram) read this env var at construction time;
+      # there is no constructor keyword on MetricsExporter for this in v0.8.0.
+      ENV["OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE"] = "delta"
+
+      exporter = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+        endpoint: "#{config.endpoint}/v1/metrics",
+        headers: {
+          "Authorization"  => "Bearer #{config.api_key}",
+          "X-Service-Name" => config.resolved_service_name,
+          "X-Environment"  => config.environment,
+        }
+      )
+
+      reader = OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
+        exporter: exporter,
+        export_interval_millis: 60_000,
+        export_timeout_millis:  10_000
+      )
+
+      provider = OpenTelemetry::SDK::Metrics::MeterProvider.new(
+        resource: OpenTelemetry.tracer_provider.resource
+      )
+      provider.add_metric_reader(reader)
+
+      OpenTelemetry.meter_provider = provider
+
+      @meter = provider.meter(
+        config.resolved_service_name,
+        version: Tracelit::VERSION
+      )
+
+      install_rails_subscriber       if defined?(::Rails)
+      install_sidekiq_middleware      if defined?(::Sidekiq)
+      install_connection_pool_poller  if defined?(::ActiveRecord)
+      install_memory_poller
+    rescue StandardError => e
+      OpenTelemetry.logger.warn("Tracelit: failed to set up metrics: #{e.message}")
+    end
+
+    def self.meter
+      @meter
+    end
+
+    # Exposes a counter for manual instrumentation in user code:
+    #   Tracelit::Metrics.counter("orders.placed").add(1)
+    def self.counter(name, description: "", unit: "")
+      @meter&.create_counter(name,
+        description: description,
+        unit: unit
+      )
+    end
+
+    def self.histogram(name, description: "", unit: "")
+      @meter&.create_histogram(name,
+        description: description,
+        unit: unit
+      )
+    end
+
+    def self.gauge(name, description: "", unit: "")
+      @meter&.create_gauge(name,
+        description: description,
+        unit: unit
+      )
+    end
+
+    # Subscribes to Rails process_action.action_controller to emit:
+    #   http.server.request.count    — counter per request
+    #   http.server.request.duration — histogram in milliseconds
+    #   http.server.error.count      — counter for 5xx responses
+    #   db.query.duration            — histogram for ActiveRecord time per request
+    def self.install_rails_subscriber
+      request_counter = @meter.create_counter(
+        "http.server.request.count",
+        description: "Total HTTP requests processed",
+        unit: "{requests}"
+      )
+
+      duration_histogram = @meter.create_histogram(
+        "http.server.request.duration",
+        description: "HTTP request duration",
+        unit: "ms"
+      )
+
+      error_counter = @meter.create_counter(
+        "http.server.error.count",
+        description: "Total HTTP 5xx responses",
+        unit: "{errors}"
+      )
+
+      db_duration_histogram = @meter.create_histogram(
+        "db.query.duration",
+        description: "Database query duration",
+        unit: "ms"
+      )
+
+      ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        payload = event.payload
+
+        attrs = {
+          "http.method"      => payload[:method].to_s,
+          "http.route"       => payload[:path].to_s,
+          "http.status_code" => payload[:status].to_s,
+          "controller"       => payload[:controller].to_s,
+          "action"           => payload[:action].to_s,
+        }
+
+        request_counter.add(1, attributes: attrs)
+        duration_histogram.record(event.duration, attributes: attrs)
+
+        error_counter.add(1, attributes: attrs) if payload[:status].to_i >= 500
+
+        if payload[:db_runtime]
+          db_duration_histogram.record(
+            payload[:db_runtime].to_f,
+            attributes: { "controller" => payload[:controller].to_s }
+          )
+        end
+      rescue StandardError
+        # Never let metric errors surface to the application
+      end
+    end
+
+    # Installs a Sidekiq server middleware that emits per-job metrics.
+    # Uses a dynamically defined class so the instrument references are
+    # captured in the closure without global state.
+    def self.install_sidekiq_middleware
+      job_counter = @meter.create_counter(
+        "sidekiq.job.count",
+        description: "Total Sidekiq jobs processed",
+        unit: "{jobs}"
+      )
+
+      job_duration = @meter.create_histogram(
+        "sidekiq.job.duration",
+        description: "Sidekiq job execution duration",
+        unit: "ms"
+      )
+
+      job_error_counter = @meter.create_counter(
+        "sidekiq.job.error.count",
+        description: "Total Sidekiq jobs that raised an error",
+        unit: "{jobs}"
+      )
+
+      _job_counter       = job_counter
+      _job_duration      = job_duration
+      _job_error_counter = job_error_counter
+
+      middleware_class = Class.new do
+        define_method(:call) do |_worker, msg, queue, &block|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          error_raised = false
+
+          begin
+            block.call
+          rescue StandardError
+            error_raised = true
+            raise
+          ensure
+            elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+
+            attrs = {
+              "sidekiq.job.class" => msg["class"].to_s,
+              "sidekiq.queue"     => queue.to_s,
+              "sidekiq.status"    => error_raised ? "error" : "success",
+            }
+
+            _job_counter.add(1, attributes: attrs)
+            _job_duration.record(elapsed_ms, attributes: attrs)
+            _job_error_counter.add(1, attributes: attrs) if error_raised
+          end
+        end
+      end
+
+      Sidekiq.configure_server do |config|
+        config.server_middleware do |chain|
+          chain.add middleware_class
+        end
+      end
+    rescue StandardError => e
+      warn "Tracelit: failed to install Sidekiq middleware: #{e.message}"
+    end
+
+    # Polls ActiveRecord connection pool stats every 30 seconds on a daemon
+    # thread and records them as gauges. Does not require a live connection
+    # at install time — errors during polling are silently retried next cycle.
+    def self.install_connection_pool_poller
+      pool_size = @meter.create_gauge(
+        "db.connection_pool.size",
+        description: "Maximum connections in the pool",
+        unit: "{connections}"
+      )
+
+      pool_busy = @meter.create_gauge(
+        "db.connection_pool.busy",
+        description: "Connections currently checked out",
+        unit: "{connections}"
+      )
+
+      pool_idle = @meter.create_gauge(
+        "db.connection_pool.idle",
+        description: "Connections available for checkout",
+        unit: "{connections}"
+      )
+
+      pool_waiting = @meter.create_gauge(
+        "db.connection_pool.waiting",
+        description: "Threads waiting for a connection",
+        unit: "{threads}"
+      )
+
+      thread = Thread.new do
+        Thread.current[:tracelit_pool_poller] = true
+        loop do
+          sleep 30
+          begin
+            pool  = ActiveRecord::Base.connection_pool
+            stat  = pool.stat
+            attrs = { "db.system" => pool.pool_config.db_config.adapter.to_s }
+            pool_size.record(stat[:size], attributes: attrs)
+            pool_busy.record(stat[:busy], attributes: attrs)
+            pool_idle.record(stat[:idle], attributes: attrs)
+            pool_waiting.record(stat[:waiting], attributes: attrs)
+          rescue StandardError
+            # Pool may not be connected yet — retry next cycle
+          end
+        end
+      end
+      thread.abort_on_exception = false
+      thread
+    rescue StandardError => e
+      warn "Tracelit: failed to install connection pool poller: #{e.message}"
+    end
+
+    # Polls process RSS memory every 60 seconds on a daemon thread using ps,
+    # which works on both macOS (arm64-darwin) and Linux without /proc.
+    def self.install_memory_poller
+      memory_gauge = @meter.create_gauge(
+        "process.memory.rss",
+        description: "Process resident set size (RSS)",
+        unit: "MB"
+      )
+
+      pid = Process.pid
+
+      thread = Thread.new do
+        Thread.current[:tracelit_memory_poller] = true
+        loop do
+          sleep 60
+          begin
+            rss_kb = `ps -o rss= -p #{pid} 2>/dev/null`.strip.to_i
+            next if rss_kb == 0
+
+            rss_mb = rss_kb / 1024.0
+            memory_gauge.record(rss_mb, attributes: {
+              "process.pid"     => pid.to_s,
+              "process.runtime" => "ruby",
+            })
+          rescue StandardError
+            # Ignore — ps may not be available in all environments
+          end
+        end
+      end
+      thread.abort_on_exception = false
+      thread
+    rescue StandardError => e
+      warn "Tracelit: failed to install memory poller: #{e.message}"
+    end
+  end
+end

data/lib/tracelit/rails_logger_bridge.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Tracelit
+  # RailsLoggerBridge adds an OpenTelemetry log emitter to Rails.logger
+  # so that every Rails.logger call is also forwarded to the OTel
+  # LoggerProvider and exported via OTLP to the Tracelit logs table.
+  #
+  # It works by broadcasting a lightweight Logger subclass (OTelLogger)
+  # alongside the existing logger. In Rails 7.1+, Rails.logger is already
+  # an ActiveSupport::BroadcastLogger, so we call broadcast_to directly.
+  # In older setups we wrap it in a new BroadcastLogger.
+  #
+  # Severity mapping (OTel SeverityNumber spec):
+  #   Rails DEBUG (0) → OTel 5  (SEVERITY_NUMBER_DEBUG)
+  #   Rails INFO  (1) → OTel 9  (SEVERITY_NUMBER_INFO)
+  #   Rails WARN  (2) → OTel 13 (SEVERITY_NUMBER_WARN)
+  #   Rails ERROR (3) → OTel 17 (SEVERITY_NUMBER_ERROR)
+  #   Rails FATAL (4) → OTel 21 (SEVERITY_NUMBER_FATAL)
+  #   Rails UNKNOWN   → OTel 1  (SEVERITY_NUMBER_TRACE)
+  module RailsLoggerBridge
+    SEVERITY_MAP = [5, 9, 13, 17, 21, 1].freeze
+
+    def self.install(logger_provider)
+      return unless defined?(::Rails) && ::Rails.logger
+
+      otel_logger = logger_provider.logger(
+        name:    "rails",
+        version: Tracelit::VERSION
+      )
+
+      otel_sink = OTelLogger.new(otel_logger)
+
+      if ::Rails.logger.is_a?(ActiveSupport::BroadcastLogger)
+        ::Rails.logger.broadcast_to(otel_sink)
+      else
+        ::Rails.logger = ActiveSupport::BroadcastLogger.new(
+          ::Rails.logger,
+          otel_sink
+        )
+      end
+    rescue StandardError => e
+      warn "Tracelit: failed to install Rails logger bridge: #{e.message}"
+    end
+
+    # OTelLogger is a Logger subclass whose add method emits an OTel LogRecord
+    # instead of writing to an IO device. It is added as a broadcast target so
+    # the original Rails logger output is preserved.
+    #
+    # The SDK Logger#on_emit defaults context: to OpenTelemetry::Context.current,
+    # which automatically correlates the log record to the current active span
+    # (trace_id + span_id) without any extra work here.
+    class OTelLogger < ::Logger
+      def initialize(otel_logger)
+        # Discard output — this logger only emits OTel records
+        super(File::NULL)
+        @otel_logger = otel_logger
+        # Accept all severities so we don't filter below the original logger
+        self.level = ::Logger::DEBUG
+      end
+
+      def add(severity, message = nil, progname = nil)
+        severity_number = SEVERITY_MAP[severity.to_i] || 9
+        severity_text   = ::Logger::SEV_LABEL[severity.to_i] || "ANY"
+
+        body = if message.nil?
+          block_given? ? yield : progname
+        else
+          message
+        end
+
+        @otel_logger.on_emit(
+          timestamp:       Time.now,
+          severity_number: severity_number,
+          severity_text:   severity_text,
+          body:            body.to_s
+        )
+      rescue StandardError
+        # Never let OTel errors surface to the application
+      end
+      alias_method :log, :add
+
+      def close; end
+    end
+  end
+end

data/lib/tracelit/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tracelit
+  # Railtie hooks Tracelit into the Rails boot sequence automatically.
+  # No explicit initializer call needed — adding the gem to the Gemfile
+  # is sufficient for Rails apps.
+  class Railtie < ::Rails::Railtie
+    # Run after the app is initialized so config/initializers/ have
+    # already been evaluated and Tracelit.configure { } blocks applied.
+    initializer "tracelit.configure", after: :load_config_initializers do
+      Tracelit::Instrumentation.setup(Tracelit.config)
+    end
+  end
+end

data/lib/tracelit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tracelit
+  VERSION = "0.1.0"
+end

data/lib/tracelit.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "tracelit/version"
+require_relative "tracelit/configuration"
+require_relative "tracelit/instrumentation"
+
+module Tracelit
+  class << self
+    # Global configuration instance. Thread-safe after boot — configure
+    # once in an initializer, read-only thereafter.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the configuration object for block-style setup:
+    #
+    #   Tracelit.configure do |config|
+    #     config.api_key      = "tl_live_abc123"
+    #     config.service_name = "payments-api"
+    #     config.environment  = "production"
+    #     config.sample_rate  = 0.2
+    #   end
+    #
+    def configure
+      yield config
+    end
+
+    # Manually trigger SDK setup. Not needed for Rails — the Railtie
+    # handles this automatically. Call explicitly for Sinatra/Rack:
+    #
+    #   Tracelit.start!
+    #
+    def start!
+      Instrumentation.setup(config)
+    end
+
+    # Returns the OpenTelemetry tracer for this service.
+    # Use for manual instrumentation of custom operations:
+    #
+    #   Tracelit.tracer.in_span("my_operation") do |span|
+    #     span.set_attribute("order.id", order.id)
+    #     do_work
+    #   end
+    #
+    def tracer
+      OpenTelemetry.tracer_provider.tracer(
+        config.resolved_service_name,
+        VERSION
+      )
+    end
+
+    # Returns the Tracelit metrics interface for manual instrumentation:
+    #
+    #   Tracelit.metrics.counter("payments.processed").add(1,
+    #     attributes: { "currency" => "USD" }
+    #   )
+    #
+    def metrics
+      Tracelit::Metrics
+    end
+  end
+end
+
+# Auto-require Railtie when Rails is present.
+require_relative "tracelit/railtie" if defined?(::Rails::Railtie)

data/tracelit.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/tracelit/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "tracelit"
+  spec.version       = Tracelit::VERSION
+  spec.authors       = ["Tracelit"]
+  spec.email         = ["hey@tracelit.io"]
+  spec.summary       = "Official Ruby SDK for Tracelit backend observability"
+  spec.description   = "Drop-in OpenTelemetry instrumentation for Rails, Sinatra, " \
+                       "and Rack apps. Sends traces, metrics, and logs to the " \
+                       "Tracelit ingest API via OTLP/HTTP."
+  spec.homepage      = "https://tracelit.io"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "tracelit.gemspec",
+    "README.md"
+  ]
+
+  spec.require_paths = ["lib"]
+
+  # Core OTel runtime dependencies
+  spec.add_dependency "opentelemetry-sdk",                 "~> 1.4"
+  spec.add_dependency "opentelemetry-exporter-otlp",       "~> 0.26"
+  spec.add_dependency "opentelemetry-instrumentation-all", "~> 0.62"
+  spec.add_dependency "opentelemetry-logs-sdk",            "~> 0.5"
+  spec.add_dependency "opentelemetry-exporter-otlp-logs",  "~> 0.4"
+  spec.add_dependency "opentelemetry-metrics-sdk",            "~> 0.13"
+  spec.add_dependency "opentelemetry-exporter-otlp-metrics",  "~> 0.8"
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: tracelit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tracelit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-all
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.62'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.62'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-logs-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp-logs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-metrics-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp-metrics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Drop-in OpenTelemetry instrumentation for Rails, Sinatra, and Rack apps.
+  Sends traces, metrics, and logs to the Tracelit ingest API via OTLP/HTTP.
+email:
+- hey@tracelit.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/tracelit.rb
+- lib/tracelit/configuration.rb
+- lib/tracelit/error_always_on_sampler.rb
+- lib/tracelit/error_span_processor.rb
+- lib/tracelit/instrumentation.rb
+- lib/tracelit/metrics.rb
+- lib/tracelit/rails_logger_bridge.rb
+- lib/tracelit/railtie.rb
+- lib/tracelit/version.rb
+- tracelit.gemspec
+homepage: https://tracelit.io
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for Tracelit backend observability
+test_files: []