open-telemetry / open-telemetry/opentelemetry-ruby
Release sequencing for instrumentation-only metrics and logs
@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:
- API change, matching SDK change, and the shim, in one PR.
- Release the API gem.
- 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. - Release the SDK gem.
Then in contrib:
- Merge the
Instrumentation::BasePR that adds meter and logger alongside the tracer. This depends on both API gems being published. Then releaseinstrumentation-base. instrumentation-loggerandinstrumentation-openaiswitch toBase#logger, once
instrumentation-baseis 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.