OpenTelemetry Ruby: many gems, and signals at different maturities

One repository, a directory per gem

The layout of the repository is the quickest way to understand what the project is. There is an `api/` directory for the interface layer, an `sdk/` directory for the implementation, and an `sdk_experimental/` directory sitting beside it for the parts that are still moving. The same split is repeated for the newer signals, with `metrics_api/` and `metrics_sdk/` and `logs_api/` and `logs_sdk/`. Alongside those sit `exporter/`, `propagator/`, `registry/`, `common/` and `semantic_conventions/`, which are the pieces that carry spans and metrics out of the process, propagate context across a wire, and define the attribute names.

That directory structure is the API and SDK separation made physical. An application depends on the API and calls into it, while the SDK and the exporters are a deployment decision, which is the property that lets a service be instrumented once and shipped to different backends. The repository also carries `docs/`, `examples/`, `test_helpers/`, a `contrib/` directory, and the usual project files, including a CODEOWNERS file, an AGENTS.md, a CLAUDE.md, a Rakefile, a Gemfile and a `.toys/` directory for build tasks.

The 0.x version numbers are a policy, not a bug

OpenTelemetry Ruby follows the versioning and stability document in the OpenTelemetry specification, and the project calls out one part of it specifically: the version numbering exception that states experimental signals may have a `0.x` version number. That single rule explains the release list. The most recent releases are opentelemetry-metrics-sdk at 0.21.0, opentelemetry-metrics-api at 0.10.0 and opentelemetry-logs-sdk at 0.8.1, all published on 2026-10-13, and the 0.x on each of them is the specification's way of saying the signal is not frozen.

The practical consequence is that the API and SDK gems for a given signal move at different speeds, so the metrics API and the metrics SDK were not at the same version on the same day. For anyone writing a Gemfile, that means pinning the pair you depend on rather than assuming the two numbers track each other, and it means treating a metrics attribute name or a logs field as something that can still change. The last push to the repository was on 2026-10-20, so the work is current.

Instrumentation for Rails lives in the contrib repository

The repository you are looking at does not contain the instrumentation for popular web frameworks. That sits in a separate repository, opentelemetry-ruby-contrib, which holds instrumentation libraries for many popular Ruby gems including Rails, Rack and Sinatra, and the point of the split is stated plainly: it lets you start using OpenTelemetry with minimal changes to your application.

The reason for the split is structural rather than stylistic. A Rails instrumentation has to track Rails releases, and a library that depends on Rails cannot be published from the same repository as the vendor neutral API without pulling the framework into everyone's dependency tree. Containing it there means the core client stays small and the framework specific code lives where it can be versioned against the framework. The contrib repository also carries the OpenSSF scorecard badge in this repository's overview, so the two are tracked as related but separate projects, and the docs link to the contrib readme for the detail on each instrumentation.

The examples are the fastest route in

Rather than a long install guide, the repository points at two things: a getting started guide hosted on opentelemetry.io for the Ruby language, and a set of examples in the repository itself. The example directories are named for what they show, with a dice roller, a plain HTTP example, and separate directories for the logs SDK and the metrics SDK, plus an example that points at an OpenTelemetry Collector. That last one matters, because a collector is the usual way to get spans and metrics out of a process in a way that is not tied to one vendor, and an example that wires the client up to a collector is more instructive than a paragraph describing it.

The contribution instructions are in a separate contributing document, which covers setting up the environment, running the tests and opening pull requests, and the project notes point at it as the place for the important information. The Ruby special interest group meets regularly and the community page for the language groups is where that is described.

The development container runs as a non-root user

The project ships a Dockerfile and a Compose file so that contributors work in the same environment. The Compose file defines a shared configuration block with a base image, a tmpfs for /tmp, a tty, a non-root user of 1000:1000 and volumes for the working directory and the bundle, and the app service merges that block and builds from the repository root:

services:
  app:
    <<: *base
    build:
      context: .
    working_dir: /app

volumes:
  bundle:

The image itself is built on a pinned Alpine Ruby base:

FROM ruby:3.3.12-alpine3.23@sha256:11da101dfad607c6193a921abc815c989bc9f19b43f5f686bbcc7d424298d596 as ruby

The system packages installed include the build toolchain, libxml2 and libxslt development headers, OpenSSL, and the mariadb and postgresql development packages, which tells you that the test suite runs against real databases rather than substitutes. The Bundler version is pinned as an argument, the gem home lives at /bundle, and the parallel job and retry counts for Bundler are set as environment variables. The container runs as the unprivileged app user rather than root, with a writable tmp directory in the app folder and the bundle path.

Who maintains it, and what the compatibility promise is

The project notes list the maintainers with their employers, which is a useful signal about where the work comes from: Daniel Azuma at Google, Francis Bogsanyi and Robert Laurin at Shopify, Kayla Reopelle at New Relic and Matthew Wear at Dash0, with two approvers from Honeycomb and SolarWinds, and four emeritus approvers and triagers. The roles themselves are defined in the community repository, which documents what a maintainer, an approver and an emeritus approver or triager actually do.

The compatibility statement is short: the project ensures compatibility with the current supported versions of the Ruby language, which is a moving target tied to the upstream Ruby release cycle rather than a fixed list in the project notes. The licence is Apache 2.0, and the project notes carry a licence status badge and a security status badge from FOSSA alongside the OpenSSF scorecard badge, so the project publishes machine checked signals about its own supply chain rather than only prose assurances.

Editorial conclusion

OpenTelemetry Ruby suits a team running Rails, Rack or Sinatra services that want traces, metrics and logs through one vendor neutral pipeline, because the API and SDK separation keeps instrumentation in the application and vendor choice in configuration, and the contrib repository means most applications need no custom spans at all. It is the wrong choice if you need the metrics or logs signals to be stable APIs, since those gems are still published under 0.x versions under the project's own versioning rules, and it is the wrong choice if you want a single gem to depend on, because the repository is many gems with different release cadences. Before you pin versions, check which signal each gem covers, since the metrics SDK, metrics API and logs SDK were all released on 2026-10-13 at different version numbers, and read the getting started guide on the OpenTelemetry site, because the repository itself does not document the install steps.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. open-telemetry/opentelemetry-ruby on GitHub
3. Project website
4. README
5. Releases