# Ruby API, context, and tests

## Tracing

Application and library code obtains a tracer from the global API. Use a stable instrumentation
scope name (normally the gem or library name), not a request-specific value.

```ruby
require 'opentelemetry'

tracer = OpenTelemetry.tracer_provider.tracer('checkout.pricing', '1.0.0')

tracer.in_span('price.quote', kind: :internal, attributes: { 'product.id' => product_id }) do |span|
  span.add_event('discount.applied', attributes: { 'discount.code' => code })
  calculate_price
end
```

`in_span` makes the span current, records an escaping exception by default, marks the span as
error, re-raises, and finishes it. Avoid recording the same exception twice: either rely on that
behavior or pass `record_exception: false` and handle it deliberately. Use `start_span` only when the span lifetime crosses a block;
then activate its context and always finish it.

Span kinds are `:internal`, `:server`, `:client`, `:producer`, and `:consumer`. Choose attributes
from the released semantic conventions; do not put unbounded identifiers or sensitive payloads
into attributes.

## Propagation and fiber-local context

The default propagators are W3C Trace Context and Baggage. Instrumentation libraries normally
inject and extract automatically. For a custom carrier:

```ruby
headers = {}
OpenTelemetry.propagation.inject(headers)

parent = OpenTelemetry.propagation.extract(incoming_headers)
OpenTelemetry::Context.with_current(parent) do
  tracer.in_span('message.consume', kind: :consumer) { consume }
end
```

Ruby context is stored per `Fiber`. If manual code calls `OpenTelemetry::Context.attach`, pair it
with `detach(token)` in `ensure`; unbalanced calls leak the active context into later work. Verify
context behavior when an application mixes threads, fibers, async schedulers, or process forks.

## Experimental metrics

Metrics remain in separate `0.x` gems. After requiring and configuring the metrics SDK:

```ruby
meter = OpenTelemetry.meter_provider.meter('checkout.pricing', version: '1.0.0')
quotes = meter.create_counter('pricing.quotes', unit: '1')
duration = meter.create_histogram('pricing.quote.duration', unit: 's')

quotes.add(1, attributes: { 'quote.result' => 'accepted' })
duration.record(elapsed, attributes: { 'quote.result' => 'accepted' })
```

Keep metric attributes bounded. Use views to drop or allowlist attributes when third-party
instrumentation would otherwise create excessive cardinality. Check the locked metrics SDK
README for supported instruments, views, exemplars, and temporality because the API is experimental.

## Experimental logs and the Logger bridge

The Logs API/SDK are also separate `0.x` gems. Applications usually bridge an existing logging
library rather than replacing it. For Ruby's standard `Logger`, install and configure
`opentelemetry-instrumentation-logger`; consult its README for options and emitted fields.
Direct `LoggerProvider#logger(name:, version:).on_emit(...)` is intended for instrumentation libraries and
advanced integrations, not as a requirement to rewrite application logging.

## Tests

Use in-memory exporters for focused tests and clear them between examples. Assert stable contract
facts—span name, kind, parent, status, and bounded attributes—rather than exporter serialization.
The core repository ships `opentelemetry-test-helpers`,
`OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter`, and analogous in-memory metric readers.

For integration tests, send to a disposable local OTLP receiver and verify the whole path. Never
point a test at a production endpoint.

Sources: [Ruby API 1.11.1](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-api/v1.11.1/api),
[metrics API 0.8.0](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.8.0/metrics_api), and
[logs SDK 0.7.0 examples](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-logs-sdk/v0.7.0/examples/logs_sdk).

# Ruby upgrade and breaking-change review

## Inventory the locked graph

```sh
bundle list | rg 'opentelemetry'
bundle outdated --strict | rg 'opentelemetry'
bundle info opentelemetry-sdk
```

Review the `Gemfile.lock`, not only direct dependencies. Core, semantic conventions, exporters,
experimental signals, and each contrib instrumentation gem publish independently.

## Classify each changed gem

| Group | Typical gems | Review focus |
|---|---|---|
| Stable tracing | `opentelemetry-api`, `opentelemetry-sdk` | API/SDK changelogs, Ruby minimum, sampler/processor behavior |
| Trace export | `opentelemetry-exporter-otlp` | protocol, endpoint construction, TLS, headers, retries |
| Experimental metrics | `opentelemetry-metrics-*`, `opentelemetry-exporter-otlp-metrics` | every minor release may break API, aggregation, cardinality, exemplars, temporality |
| Experimental logs | `opentelemetry-logs-*`, `opentelemetry-exporter-otlp-logs` | every minor release may break API, limits, processors, event fields |
| Contrib | `opentelemetry-instrumentation-*`, propagators, resource detectors | target-gem compatibility, Ruby minimum, span names/attributes, options |
| Semantic conventions | `opentelemetry-semantic_conventions` | generated constants, stability namespace, emitted-schema migration |

Do not align versions by number across groups. A valid bundle can contain `1.x` tracing gems and
different `0.x` metrics, logs, exporter, and instrumentation versions.

## Ruby and target-library compatibility

Check both core and contrib requirements. Current core and relevant contrib releases require Ruby
3.3 or newer, but an older locked release may have a different range. Rails instrumentation
`0.42.0` additionally requires Rails 7.1 or newer. Each instrumentation gemspec constrains the
framework/client versions it supports. Upgrade Ruby, Rails, or a client library and its OTel
instrumentation as one compatibility decision.

## Behavioral review

Read every changed gem's changelog from the old locked version through the proposed one. Search for:

- `BREAKING CHANGE`, minimum Ruby changes, and removed/deprecated APIs;
- new default exporters or protocols;
- sampler, batch processor, fork, shutdown, and timeout changes;
- metric aggregation, temporality, exemplar, or cardinality changes;
- log attribute-limit and event-field changes;
- semantic-convention migrations and span-name/attribute changes;
- expanded or narrowed target-library version constraints.

Recent examples: metrics API `0.8.0` / SDK `0.19.0` (and SDK `0.18.0` / OTLP metrics exporter
`0.12.0`) are marked `BREAKING CHANGE` for spec alignment and change the internal instrument-creation
signature that custom SDKs or proxies implement; logs API `0.5.0` changes `LoggerProvider#logger` to
keyword arguments (`logger(name:, version: nil)`), so positional calls in custom bridges break; trace
OTLP exporter `0.37.0` changes its default compression (see [setup.md](setup.md#environment-configuration)).

For contrib, inspect the released gem's README, gemspec, and tests when the changelog does not fully
describe emitted telemetry.

## Verification path

1. Run `bundle update <explicit OTel gems>` rather than a broad unrelated update.
2. Inspect `git diff -- Gemfile Gemfile.lock` and explain every changed OTel/transitive gem.
3. Run the repository's tests and boot checks on each supported Ruby/framework combination.
4. Exercise representative requests, database calls, and jobs against a disposable OTLP receiver.
5. Compare span names, attributes, parentage, metrics temporality/cardinality, logs, and shutdown.
6. Audit dashboards, alerts, sampling rules, and Collector processors for renamed telemetry.

Sources: [core changelogs](https://github.com/open-telemetry/opentelemetry-ruby),
[contrib changelogs](https://github.com/open-telemetry/opentelemetry-ruby-contrib), and
[OpenTelemetry Ruby releases](https://github.com/open-telemetry/opentelemetry-ruby/releases).

# Ruby instrumentation libraries

## Discover before adding

Inspect the lockfile and bootstrap first:

```sh
bundle list | rg 'opentelemetry|rails|rack|sinatra|sidekiq|faraday|net-http|pg|mysql2|redis'
rg -n "OpenTelemetry::SDK.configure|\.use_all|OpenTelemetry::Instrumentation" .
```

Avoid double instrumentation. Rails can pull together Rack, Action Pack, Active Record, Active
Job, and other libraries; adding lower-level instrumentation separately is useful only when its
configuration or coverage is intentionally required.

## Installation modes

For a bounded surface, install a gem and select its registered constant:

```ruby
gem 'opentelemetry-instrumentation-rack'
gem 'opentelemetry-instrumentation-sidekiq'

OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::Rack'
  c.use 'OpenTelemetry::Instrumentation::Sidekiq'
end
```

For discovery, install `opentelemetry-instrumentation-all` and call `c.use_all`. It installs only
registered instrumentations whose dependency checks pass. Pass a per-instrumentation options hash
or `{ enabled: false }` for exclusions. Do not mix `use` with `use_all`.

## Find the maintained library

The source of truth is the contrib repository's
[`instrumentation/`](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/opentelemetry-instrumentation-all/v0.97.0/instrumentation)
directory. It currently includes categories such as:

| Area | Examples |
|---|---|
| Web and Rails | Rails, Rack, Sinatra, Grape, Action Pack/View/Mailer, Active Support |
| HTTP and RPC | Net::HTTP, Faraday, HTTP.rb, HTTPX, Excon, Ethon, RestClient, gRPC |
| Databases and caches | Active Record, PG, mysql2, Trilogy, Mongo, Redis, Dalli, LMDB |
| Jobs and messaging | Active Job, Sidekiq, Resque, Delayed Job, Que, Bunny, ruby-kafka, Racecar, rdkafka |
| Runtime and testing | concurrent-ruby, Logger, Rake, RSpec, Factory Bot |
| Cloud and AI | AWS SDK/Lambda, Anthropic |

This table is a routing aid, not a package/version inventory. Before recommending a gem, open its
README and gemspec in the locked release to confirm its target-library range, Ruby requirement,
registered constant, options, and emitted semantic-convention mode.

As of 2026-10-03, the latest relevant releases are Rails `0.42.0` (Ruby >= 3.3, Rails >= 7.1),
Rack `0.31.2`, Sinatra `0.30.1`, Sidekiq `0.29.0`, Logger `0.4.0`, and the `all` bundle `0.97.0`.
The latter five also require Ruby >= 3.3. Do not transfer these constraints to an older lockfile.

## Framework ordering

Configure instrumentation before the target library begins serving work. Rails instrumentation
uses a Railtie, but its initializer still needs to load during application boot. Rack middleware
and monkey-patching instrumentations can miss setup work or duplicate spans if installed after an
application/server integration has already initialized.

For background jobs and message consumers, verify both producer injection and consumer extraction.
For database and HTTP instrumentation, verify that sensitive statements, URLs, and headers are not
captured unintentionally. Use the relevant library's filtering and sanitization options rather
than post-processing data blindly.

## Semantic-convention changes

Instrumentation gems can change emitted span names and attributes independently of core SDK gems.
During an upgrade, compare the affected gem's changelog and tests, then audit dashboards, alerts,
sampling rules, and processors that depend on legacy names. Use `otel-semantic-conventions` for the
released convention, but use the instrumentation release itself to prove what Ruby actually emits.

## Verification

Exercise one representative operation per installed integration and check:

- exactly one expected client/server/producer/consumer span;
- correct parentage across process boundaries;
- route templates rather than raw high-cardinality paths where supported;
- bounded, non-sensitive attributes;
- no boot warning that an instrumentation is unavailable or incompatible.

# Ruby performance and lifecycle

## Start with the measured bottleneck

Separate instrumentation overhead from exporter/network delay, application allocation, and backend
ingestion. Benchmark the real framework or job path with representative concurrency and payloads.
Record throughput, latency, allocations, queue drops, and exported telemetry before changing knobs.

## Sampling and batching

Use a parent-based sampler when distributed parent decisions must be preserved. Configure standard
sampler variables before `OpenTelemetry::SDK.configure`:

```sh
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
```

The default OTLP trace path uses a batch span processor. Its queue, delay, batch, timeout, and
thread-start behavior are configurable in the locked SDK release. Inspect the constructor and
standard `OTEL_BSP_*` variables before tuning; `OTEL_RUBY_BSP_START_THREAD_ON_BOOT` is Ruby-specific.
Larger queues can reduce transient drops but retain more objects. A simple processor exports on the
request path and is unsuitable for normal production traffic.

## Forks, threads, and fibers

Pre-fork servers copy provider and processor state. Verify the exact SDK/server combination rather
than assuming a background export thread survives. The released batch span processor and metrics
SDK include fork handling, but startup timing, inherited buffers, logs processing, and graceful
shutdown still matter. Exercise a request in a worker and prove each enabled signal exports after
the fork.

Context is fiber-local. Test parentage across any custom thread pools, fibers, async schedulers,
jobs, and callbacks that framework instrumentation does not already cover.

## Metrics cardinality and cost

The experimental metrics SDK applies cardinality limits (default 2000 per stream in `0.19.0`) and
supports views. Prefer bounded
dimensions; use a view to retain only useful attribute keys or drop a noisy instrument. Confirm
the locked release's limit and overflow behavior before relying on it. Check delta/cumulative
temporality against the receiving backend when changing the OTLP metrics preference.

## Attribute and payload bounds

Use standard `OTEL_ATTRIBUTE_*`, `OTEL_SPAN_*`, event, and link limits supported by the locked SDK.
Ruby also accepts `OTEL_RUBY_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` for compatibility, but prefer the
standard variable for new configuration. Limits protect process memory and payload size; they do
not make sensitive values safe to collect.

## Export and shutdown

- Prefer OTLP through a nearby Collector over synchronous export from request handling.
- Use compression only after measuring CPU and network impact.
- Keep exporter timeouts bounded below the application's shutdown budget.
- Call provider `shutdown` from the server/job lifecycle so queued telemetry is flushed.
- Use `force_flush(timeout: ...)` for bounded checkpoints, not on every request.

An empty backend query is not proof of zero telemetry. Enable `OTEL_LOG_LEVEL=debug`, inspect SDK
warnings and processor drop signals, and compare with a disposable local receiver.

Sources: [trace SDK 1.13.1](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-sdk/v1.13.1/sdk),
[metrics SDK 0.19.0](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-sdk/v0.19.0/metrics_sdk), and
[Ruby API 1.11.1 benchmarks](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-api/v1.11.1/api/benchmarks).

# Ruby SDK setup

## Choose gems by signal

For stable tracing, applications normally need the SDK, an exporter, and only the
instrumentation they use:

```ruby
# Gemfile
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-rails'
gem 'opentelemetry-instrumentation-sidekiq'
gem 'opentelemetry-instrumentation-logger'
```

Libraries that create spans should depend only on `opentelemetry-api`. Exporters and SDK setup
belong to the application. The convenience gem `opentelemetry-instrumentation-all` enables
runtime discovery with `use_all`, but explicit instrumentation gems plus `use` make the installed
surface easier to audit.

Metrics and logs require separate experimental gems. Add only the signals the application will
emit and export:

```ruby
gem 'opentelemetry-metrics-api'
gem 'opentelemetry-metrics-sdk'
gem 'opentelemetry-exporter-otlp-metrics'

gem 'opentelemetry-logs-api'
gem 'opentelemetry-logs-sdk'
gem 'opentelemetry-exporter-otlp-logs'
```

Do not give these gems the tracing SDK's version. Let Bundler resolve compatible releases, then
review the lockfile and each changed gem's changelog.

## Configure once, before application work

Require the selected exporter and instrumentation gems before configuration. In Rails, place the
configuration in an initializer; in Rack/Sinatra or a worker, run it during bootstrap.
Use `OTEL_*` environment variables and `OpenTelemetry::SDK.configure`. The separate experimental
`opentelemetry-config` gem (first released `0.1.0`, 2026-09-29) reads an `OTEL_CONFIG_FILE` YAML
file, but only when the application calls `OpenTelemetry::Config.configure` (or
`configure_from_file`); it covers the tracer provider, resource, samplers, and propagators only, and
per its README does not yet give the file precedence over environment variables. For the YAML schema
see the `otel-declarative-config` skill; check the locked gem's README before relying on it.
Requiring the metrics and logs SDKs before
`configure` installs their configurator hooks; their default exporter is OTLP when the matching
exporter gem is loaded.

```ruby
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry-metrics-sdk'
require 'opentelemetry/exporter/otlp_metrics'
require 'opentelemetry-logs-sdk'
require 'opentelemetry/exporter/otlp_logs'
require 'opentelemetry/instrumentation/rails'
require 'opentelemetry/instrumentation/sidekiq'
require 'opentelemetry/instrumentation/logger'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'checkout'
  c.service_version = ENV.fetch('APP_VERSION', 'unknown')
  c.use 'OpenTelemetry::Instrumentation::Rails'
  c.use 'OpenTelemetry::Instrumentation::Sidekiq'
  c.use 'OpenTelemetry::Instrumentation::Logger'
end
```

`use` and `use_all` are mutually exclusive in one SDK configuration. `use_all` installs every
registered instrumentation whose target library is present:

```ruby
OpenTelemetry::SDK.configure do |c|
  c.use_all(
    'OpenTelemetry::Instrumentation::ActiveRecord' => { enabled: false }
  )
end
```

Use each instrumentation's README for its exact constant, supported dependency versions, and
options. Do not infer a constant mechanically from a gem name.

## Environment configuration

Common inputs include:

```sh
OTEL_SERVICE_NAME=checkout
OTEL_RESOURCE_ATTRIBUTES=service.version=abc123,deployment.environment.name=production
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_PROPAGATORS=tracecontext,baggage
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
OTEL_LOG_LEVEL=info
```

The released automatic trace and log OTLP paths support `http/protobuf`; an unsupported general
or relevant signal-specific protocol disables the trace or log exporter with a warning. The
metrics path does not read protocol variables and uses its HTTP/protobuf `MetricsExporter`.
The core repository contains an `opentelemetry-exporter-otlp-grpc` prototype, but its changelog
marks it unreleased and not production-ready. Do not recommend it until a released gem says
otherwise. OTLP compression defaults differ by signal: the trace exporter defaults to `none` since
`opentelemetry-exporter-otlp` `0.37.0`, while the metrics and logs exporters default to `gzip`; set
`OTEL_EXPORTER_OTLP_COMPRESSION` (or the signal-specific variable) when a uniform choice matters.
Use signal-specific endpoints and headers when the signals differ. Never place a
secret directly in checked-in configuration.

## Lifecycle

Flush providers during graceful process termination. `shutdown` flushes processors and exporters;
calling it too early makes later telemetry no-op or fail export.

```ruby
at_exit do
  OpenTelemetry.tracer_provider.shutdown
  OpenTelemetry.meter_provider.shutdown if defined?(OpenTelemetry::SDK::Metrics)
  OpenTelemetry.logger_provider.shutdown if defined?(OpenTelemetry::SDK::Logs)
end
```

Framework and server shutdown hooks are preferable when they offer a bounded graceful-shutdown
phase. For short jobs, call `force_flush` before the process exits if the provider remains shared.

## Verify locally

1. Run `bundle install` and inspect `Gemfile.lock` for independently resolved OTel gems.
2. Boot once with `OTEL_LOG_LEVEL=debug` and confirm no missing exporter or instrumentation warning.
3. Send a request or execute a job against a disposable local receiver.
4. Confirm the expected resource, parent/child relationship, and shutdown export.

Sources: [core SDK 1.13.1](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-sdk/v1.13.1/sdk),
[`opentelemetry-config` 0.1.0](https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-config/v0.1.0/config),
[Ruby getting started](https://opentelemetry.io/docs/languages/ruby/getting-started/), and
[contrib instrumentation catalog at the `all` 0.97.0 release](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/opentelemetry-instrumentation-all/v0.97.0/instrumentation).