open-telemetry / open-telemetry/opentelemetry-ruby

Release sequencing for instrumentation-only metrics and logs

Open
#2,413 0 comments 0 reactions 1 assignee View on GitHub

@mwear is already working on this.

Since Sep 18, 2026.

Dominant language
Ruby
Stars
606
Forks
301
Avg merge
3d 19h
Merged PRs (30d)
42

Description

This work moves the global meter and logger providers behind an opt-in require, so instrumentation can use the unstable APIs without them becoming part of a user's surface. This issue covers how we release it to minimize impact to existing users.

One problem

opentelemetry-logs-sdk 0.6.1 and opentelemetry-metrics-sdk 0.18.0 both assign and read
the accessors this work removes, and they pin their APIs at ~> 0.1 and ~> 0.2 e.g. any version < 1.0, so bundler will resolve either SDK against a new API gem where the
accessor is gone.

The failure mode is as follows: the logs and metrics configuration hooks run before install_instrumentation, and SDK.configure rescues without re-raising. The app boots, logs an error, installs nothing, and emits no telemetry.

OpenTelemetry error: unexpected configuration error due to
undefined method 'logger_provider=' for module OpenTelemetry

Unfortunately, we can't do anything about the currently released, overly permissive pins, but I did come up with a compatibility shim that will minimize the impact. We can also pin the API more narrowly for future releases.

Compatibility shim

A legacy SDK is always loaded by the time it reaches for the accessor, so while we cannot detect one at require time, we can use method_missing to install the global at runtime. We warn the user that the global was installed via the compatibility shim and that they should upgrade their SDK.

Take a look at an example here.

With no SDK loaded trying access a global will raise a NoMethodError, so requiring an API gem on its own does not expose the API to users via the global.

The compatibility shim is temporary and removal is tracked in #2414.

SDK pins

Each new SDK should pin its API at three segments (~> 0.6.0, ~> 0.8.0). This has to be a handled as a follow-up PR, merged between the API release and the SDK release.

Sequence

Logs and metrics are independent of each other. For each signal, in core:

  1. API change, matching SDK change, and the shim, in one PR.
  2. Release the API gem.
  3. Follow-up PR bumping the SDK's pin. The SDK release PR is already open by this point,
    since step 1 touched the SDK directory. Do not merge it before this lands.
  4. Release the SDK gem.

Then in contrib:

  1. Merge the Instrumentation::Base PR that adds meter and logger alongside the tracer. This depends on both API gems being published. Then release instrumentation-base.
  2. instrumentation-logger and instrumentation-openai switch to Base#logger, once
    instrumentation-base is published. They will need to pin ~> 0.27, which is the same
    chicken and egg problem as the SDK pins above.

Expected versions. If these drift we'll need to update the pins from step 3 and ensure existing PRs are updated accordingly (warnings, etc, use anticipated versions).

gem now expected
opentelemetry-logs-api 0.5.0 0.6.0
opentelemetry-logs-sdk 0.6.1 0.7.0
opentelemetry-metrics-api 0.7.1 0.8.0
opentelemetry-metrics-sdk 0.18.0 0.19.0
opentelemetry-instrumentation-base 0.26.1 0.27.0

Note:instrumentation-logger is a breaking change. Its log records move from instrumentation
scope opentelemetry-instrumentation-logger to OpenTelemetry::Instrumentation::Logger, which matches what Base#tracer uses for spans.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.