feat(chore): declarative configuration for trace_provider by xuan-cao-swi · Pull Request #2161 · open-telemetry/opentelemetry-ruby

xuan-cao-swi · 2026-05-25T15:28:47Z

Description

This PR introduces an initial declarative configuration implementation for OpenTelemetry Ruby under otelconfig, intentionally scoped to tracing only.

I followed the Go otelconfig convention for config structure and behavior where it maps well to Ruby.

Minimalist approach: no hard dependency on optional components, which optional propagators and resource detectors are resolved only if the corresponding gem has been required by the user. If an optional component is not available, configuration continues safely with warnings instead of failing startup.

Scope in this PR

Trace configuration only:
- tracer provider setup
- samplers
- span processors
- trace exporters
- span limits
Declarative resource and propagation wiring needed for trace setup
Instrumentation mapping/installation flow for declarative config
Tests and example configuration for the implemented behavior

Try /example

Updated (2026-06-13):

The in-memory struct of opentelemetry configuration now is based on https://github.com/open-telemetry/opentelemetry-configuration/tree/v1.0.0-rc.3/schema. bundle exec rake generate:constants will auto-generate the struct file.
configuration will return RubySDK struct that contain providers, which user need to set the global provider point to the providers
```
sdk = OpenTelemetry::OtelConfig.configure
OpenTelemetry.tracer_provider = sdk.tracer_provider
```

thompson-tomo

One other thing, how are we ensuring the loading of the the env variables are disabled when covered by declarative config?

Will the current approach support dynamic reloading of the config which is also a part of the spec?

mwear

I like the approach overall. I have a few comments based on a first pass through.

mwear · 2026-07-27T20:37:54Z

+
+      private
+
+      def apply(config)


This only returns an SDK on the happy path. Other paths vary in what they return. We should define what happens on these other paths? Do we want to always return an SDK backed by no-op components or something else?

Now it will return noop sdk (e.g. noop provider and propagator) if parsing failed

Now it will also init the otel sdk for user by replacing the global provider and propagator.

mwear

Sorry, I have been slow to review the declarative config PRs. I notice we also have #21960 proposing a slightly different shape for declarative config. We should discuss further in #2127 and see if we can align on an approach.

mwear

If the comment regarding parse, create, install is addressed, then I think this has the overall shape and behavior that we want and we can consider this as our MVP and handle additional functionality incrementally.

The constructor injection that is proposed in #2196 can be handled as an internal refactor. However, we should not allow the configuration model to leak into the SDK.

There were comments suggesting that we should have support for custom components, which I agree with in spirit. There is likely a path forward using Class#inherited to build a registry of components. However there will be startup, initialization, load-order complications that need to be worked through. The spec currently lists extensions as a SHOULD, so this does not need to be included in the MVP.

Environment variable handling is another thing we're going to have to work on, but it can also be handled separately.

mwear · 2026-08-10T21:34:05Z

+
+    class << self
+      # Entry point
+      def configure


The specification says that there should be parse and create operations. Right now we only expose configure and confgure_from_file. configure has the right behavior, but I would prefer that we build it as suggested in #2127.

sdk = OpenTelemetry::Config.configure # ^^ Equivalent to vv sdk = OpenTelemetry::Config.install( OpenTelemetry::Config.create( OpenTelemetry::Config.parse(ENV['OTEL_CONFIG_FILE']))) # the SDK handle ideally should be usable for shutdown at_exit { sdk.shutdown }

parse should return the model, currently this is parse_config_file

create should return a configured RubySDK

install should take a RubySDK and assign it the proper globals

configure is a convenience method that wraps all three operations, should return a RubySDK

The current apply implementation is create + install fused. It should be split.

Not spec'd but would be nice and mirrors what Go does: the RubySDK should expose a shutdown method that fans out to the configured providers.

Thanks, configure now is separated to parse, create and install.

mwear · 2026-08-10T21:34:51Z

+require 'opentelemetry/otelconfig/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'opentelemetry-otelconfig'


I would prefer to see this named: opentelemetry-config or opentelemetry-configuration.

change the folder name from otelconfig to config as well?

changed folder name to config

…o otelconfig

xuan-cao-swi · 2026-08-11T16:08:49Z

Environment variable handling is another thing we're going to have to work on, but it can also be handled separately.

I think eventually env var will be abandoned if user specifically choose to use declarative config. There are migration from env var (otel-sdk-migration-config.yaml)

There were comments suggesting that we should have support for custom components

The only concern I have is that user have to install and load their custom components first (before declarative config) then the declarative config can recognize them, which means extra steps for user.

mwear · 2026-08-11T22:32:03Z

+
+        propagators = configure_propagation(config.propagator)
+
+        configure_instrumentation(config.instrumentation_development)


create should only construct the SDK components. Instrumentation installation should happen in install instead.

updated: create will only construct SDK conponents and instrumentation installation will only happened in install

mwear · 2026-08-11T22:35:09Z

+      # @param ruby_sdk [RubySDK]
+      # @return [RubySDK] the same SDK handle
+      def install(ruby_sdk)
+        OpenTelemetry.tracer_provider = ruby_sdk.tracer_provider if ruby_sdk.tracer_provider


install should skip the no-op SDK. As written, it will set the globals to the no-op components since the returned no-op providers are truthy. This is a change in behavior from before the apply split, which left the globals as-is.

The cleanest fix is a frozen NOOP_SDK constant returned from every no-op path, with install short circuiting when ruby_sdk.equal?(NOOP_SDK).

Updated: every no-op path will return NOOP_SDK constant and will be skipped from install

xuan-cao-swi added 4 commits May 24, 2026 23:11

feat(chore): declarative config for trace

8d11a1b

use ratio 1

76e310f

remove unnecessary comments

08d74c7

lint

9b032d4

thompson-tomo reviewed May 26, 2026

View reviewed changes

xuan-cao-swi added 7 commits June 15, 2026 10:48

return struct with providers and propagators

eeba852

gemspec

479dd93

autogenerated constants for in-memory struct

eed4d9c

update

235fa86

lint

8208d38

readme

e6065b5

merge

144e5d1

xuan-cao-swi marked this pull request as ready for review June 15, 2026 19:36

xuan-cao-swi requested review from arielvalentin, dazuma, fbogsany, kaylareopelle, mwear, robbkidd and robertlaurin as code owners June 15, 2026 19:36

Merge branch 'main' into otelconfig

0869fa9

xuan-cao-swi requested review from a team as code owners June 29, 2026 18:07

mwear reviewed Jul 27, 2026

View reviewed changes

mwear mentioned this pull request Jul 27, 2026

feat: Scaffold out declarative config #2196

Draft

mwear reviewed Jul 27, 2026

View reviewed changes

mwear mentioned this pull request Jul 27, 2026

Support Declarative configuration #2127

Open

xuan-cao-swi and others added 3 commits July 29, 2026 12:35

Merge branch 'main' into otelconfig

051799d

add OpenTelemetry::OtelConfig::Model as module name

e7cb742

return noop sdk if parsing goes wrong

d98e803

xuan-cao-swi and others added 4 commits July 29, 2026 14:18

update simplecov to 1

a7b6549

use spec.add_spec for dep

6a8d589

Merge branch 'main' into otelconfig

0fefba9

init the otel for user

85a71dd

mwear reviewed Aug 10, 2026

View reviewed changes

xuan-cao-swi added 2 commits August 11, 2026 11:19

Merge branch 'main' of github.com:xuan-cao-swi/opentelemetry-ruby int…

fb04478

…o otelconfig

revision

7579b7a

mwear reviewed Aug 11, 2026

View reviewed changes

change otelconfig -> config; revision

fb6a1e7


		propagators = configure_propagation(config.propagator)

		configure_instrumentation(config.instrumentation_development)

Uh oh!

Conversation

xuan-cao-swi commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mwear left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mwear left a comment

Choose a reason for hiding this comment

Uh oh!

mwear left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xuan-cao-swi commented Aug 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

xuan-cao-swi commented May 25, 2026 •

edited

Loading