feat: add gem for auto-instrumentation in otel-operator by xuan-cao-swi · Pull Request #1384 · open-telemetry/opentelemetry-ruby-contrib

xuan-cao-swi · 2025-01-30T18:55:02Z

Description

This PR aims to contribute a script/gem that can load the necessary OpenTelemetry-related gems and initialize the SDK for the opentelemetry-operator. The script/gem also includes a resource detector as part of its features.

The main idea was inspired by new_relic, which prepends the bundler.require function and places the loading script at the end of the loading procedure. For apps or scripts that don't use Bundler or a Gemfile, more details on variations of app loading can be found in the README. Currently, the goal is to ensure that Rails apps can work, with future improvements in mind.

The reason behind creating this gem is to facilitate easy installation and dependency enforcement. Although for the OpenTelemetry-Operator Node.js, it puts the loading script directly in the src folder (and then copy over to binding volume), it still relies on the auto-instrumentation-node package to install all required packages (e.g., API/SDK and instrumentation packages).

The main purpose of the gem is to serve the OpenTelemetry-Operator, which requires more configuration changes (see the configuration section in the README). Users don't need to modify their Ruby app codebase while using the instrumentation from OpenTelemetry-Ruby, but anyone can still use it in any environment.

The gem name, file structure, and implementation need more suggestions to make them more reasonable. I have tested it with rails and sinatra (through rackup), and I currently still in the process of testing against the opentelemetry operator cluster locally. Once the operator testing done, I will mark the pr as ready.

Related to open-telemetry/opentelemetry-operator#3756

xuan-cao-swi · 2025-02-26T19:14:43Z

We don't need to push to make the gem ready/release, but the script file need to get some review first.

github-actions · 2025-03-29T02:02:41Z

👋 This pull request has been marked as stale because it has been open with no activity. You can: comment on the issue or remove the stale label to hold stale off for a while, add the keep label to hold stale off permanently, or do nothing. If you do nothing this pull request will be closed eventually by the stale bot

github-actions · 2025-05-03T02:05:46Z

👋 This pull request has been marked as stale because it has been open with no activity. You can: comment on the issue or remove the stale label to hold stale off for a while, add the keep label to hold stale off permanently, or do nothing. If you do nothing this pull request will be closed eventually by the stale bot

thompson-tomo · 2026-04-22T16:46:51Z

@xuan-cao-swi there appears to be an issue calculating code coverage https://github.com/open-telemetry/opentelemetry-ruby-contrib/actions/runs/24790433512/job/72546108811#step:4:1 it is getting 0 lines hence classifying it as 100% coverage.

thompson-tomo · 2026-04-23T12:54:36Z

+
+    def self._otel_detect_resource_from_env
+      env = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s
+      additional_resource = ::OpenTelemetry::SDK::Resources::Resource.create({})


Shouldn't this have been added by the sdk automatically?

No, resource detector is not set for sdk by default; also this function allow user to have option to choose what resource detector to use.

Ok, that is a bug then based on https://opentelemetry.io/docs/concepts/resources/#semantic-attributes-with-sdk-provided-default-value and also https://opentelemetry.io/docs/specs/otel/resource/sdk/#sdk-provided-resource-attributes.

I have no issue with the user choosing the additional resource detectors.

Have raised open-telemetry/opentelemetry-ruby#2109 to address it.

I think the issue is that the resource is currently created by the SDK when the OpenTelemetry::SDK.configure method is called. Before the auto-instrumentation gem, the configure method needed to be called to start the SDK.

When a new Configurator is initialized, the resource is created.
configure call to create a new Configurator:
https://github.com/open-telemetry/opentelemetry-ruby/blob/559e7a0aacfed2b3f866d469c8f38889038d9bba/sdk/lib/opentelemetry/sdk.rb#L69

@resource assignment to configurator during initialization:
https://github.com/open-telemetry/opentelemetry-ruby/blob/aa6ecce6a15df71a5ad3005450d2d30f7b677348/sdk/lib/opentelemetry/sdk/configurator.rb#L42

Can the order here be changed to allow the configurator to create the resource for us? https://github.com/open-telemetry/opentelemetry-ruby-contrib/pull/1384/changes#diff-0409b7d589cb1e720c3d1d6e40646dc0e3468b97d6340b05788fc9a11a3d2e3cR126-R138

sorry, could you clarify what resource need to be reordered?
When using c.resource = new_resource, it will merge the new_resource with the default resource

arielvalentin

Note

🤖 This review was generated with AI assistance (GitHub Copilot CLI). Source code references were verified against the linked repositories.

I looked at how New Relic, Datadog, Elastic APM, and Honeycomb handle zero-code / auto-instrumentation to see how this approach compares. Overall, the Bundler prepend pattern is well-established — New Relic uses the same approach and it is the only pattern in the Ruby ecosystem that achieves truly zero-code instrumentation.

I have a few observations below. I do not want to block progress on this PR but I would like you to strongly consider these changes before we merge.

Thread Safety

The @_otel_initialized flag is checked without synchronization. In a multi-threaded server like Puma, two threads could both read false and double-initialize the SDK.

Both Elastic APM and Datadog protect their initialization with a Mutex. Would it make sense to add one here?

Hardcoded Instrumentation Map

The OTEL_INSTRUMENTATION_MAP duplicates what the SDK registry already knows. Datadog's approach iterates over a self-registering registry instead of maintaining a parallel map. Since this code already calls c.use_all when no filter is set, could we query the SDK's instrumentation registry for the selective case too? This would avoid the map drifting out of sync as new instrumentations are added.

Code Coverage

@thompson-tomo noted that SimpleCov is reporting 0 lines / 100% coverage. The subprocess fork testing is excellent for isolation but the coverage merging needs to be fixed before we merge.

✅ What I liked

The warning about bundled OTel gems is great defensive programming — none of the other APM libraries do this
The subprocess fork test architecture is really thorough
Following the proven New Relic bootstrap pattern was a good choice

arielvalentin · 2026-04-27T04:03:40Z

+module OTelBundlerPatch
+  # Nested module to handle OpenTelemetry initialization logic
+  module OTelInitializer
+    @_otel_initialized = false


Both Elastic APM and Datadog use a Mutex for their initialization guards. Would something like this work here?

@_otel_mutex = Mutex.new @_otel_initialized = false def self._otel_require_otel @_otel_mutex.synchronize do return if @_otel_initialized @_otel_initialized = true # ... rest of init end end

Added the mutex

~~@xuan-cao-swi - I don't see the mutex. Can you show me where it is?~~
Disregard -- my PR view was scoped to commits without me realizing it.

arielvalentin · 2026-04-27T04:03:40Z

+  module OTelInitializer
+    @_otel_initialized = false
+
+    OTEL_INSTRUMENTATION_MAP = {


This map will need to be updated every time a new instrumentation is added. Datadog avoids this by iterating over a self-registering registry. Since we already call c.use_all when no filter is set, could we query OpenTelemetry::Instrumentation.registry for the selective case too?

Updated to use OpenTelemetry::Instrumentation.registry

arielvalentin · 2026-04-27T04:03:40Z

+
+# Load OpenTelemetry components and their dependencies
+# googleapis-common-protos-types and google-protobuf are dependencies for otlp exporters
+loaded_library_file_path = Dir.glob("#{gem_path}/gems/*").select do |file_path|


This writes to $stdout which could pollute application output or break pipe-based workflows. Other APM libraries use loggers or stderr — Honeycomb, Elastic APM. Should we use warn or $stderr.puts instead?

Updated to use warn

arielvalentin · 2026-04-27T04:03:40Z

+  file_path.include?('opentelemetry') ||
+    file_path.include?('googleapis-common-protos-types') ||
+    file_path.include?('google-protobuf')
+end


A couple of thoughts here:

The allowlist only covers OTel + protobuf gems. If any OTel gem has transitive dependencies (e.g., faraday for OTLP HTTP export), they won't be on the load path.

file_path.include?('opentelemetry') is a substring match that could match unintended paths.

New Relic's approach is simpler because they only manage their own gem. Since we need to manage a whole ecosystem here, would it make sense to add ALL gems from the operator's gem path instead of an allowlist? Or could we use Gem.use_paths to properly register the operator gem path?

The goal here is to prevent gem conflicts.

For example, if the path /otel-auto-instrumentation-ruby includes abc-1.2.6, but the user's gem path (e.g., /home/app/.local/share/gem/ruby/3.3.0) includes abc-1.2.4, a conflict will occur if the user's Gemfile.lock specifies abc-1.2.4 while abc-1.2.6 is already activated.

To address this, I made an update to specifically disable google-protobuf or googleapis-common-protos-types if the user already has these gems installed in their original gem path. This ensures that they are not loaded from otel-auto-instrumentation-ruby, thereby avoiding potential conflicts.

Additionally, if the user wants to use Faraday instrumentation, they must ensure that Faraday is installed in their application.

arielvalentin · 2026-04-27T04:03:40Z

+require 'opentelemetry-exporter-otlp-logs'
+require 'opentelemetry-instrumentation-all'
+
+resource_detectors = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s


String#include? is a substring match — 'my-container-app'.include?('container') would also be true. The _otel_detect_resource_from_env method already handles this correctly by splitting on ,. Should we be consistent here?

Suggested change

resource_detectors = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s

resource_detectors = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s.split(',').map(&:strip)

require 'opentelemetry-resource-detector-container' if resource_detectors.include?('container')

require 'opentelemetry-resource-detector-azure' if resource_detectors.include?('azure')

require 'opentelemetry-resource-detector-aws' if resource_detectors.include?('aws')

arielvalentin · 2026-04-27T04:03:40Z

+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.add_dependency 'opentelemetry-api', '~> 1.9.0'


Do you want these to always use strict versions vs pessimistic versioning to allow for bug fixes in dependencies without requiring a new version of this gem? ~> 1.9.0 only allows patch releases (>= 1.9.0, < 1.10.0). Any minor version bump of the SDK will require a coordinated release of this gem.

Is there going to be a process that bumps these versions when the API and SDK versions are updated?

Do you want these to always use strict versions vs pessimistic versioning to allow for bug fixes in dependencies without requiring a new version of this gem?

This doesn't matter in operator's autoinstrumentation image because those are pre-build image (similar to lambda layer).

Is there going to be a process that bumps these versions when the API and SDK versions are updated?

Likely will be picked up by dependabot or renovate

…lemetry-ruby-contrib into auto-instrumentation

thompson-tomo · 2026-05-03T15:24:43Z

+    def self._otel_detect_resource_from_env
+      resource_map = {
+        'container' => (defined?(::OpenTelemetry::Resource::Detector::Container) ? ::OpenTelemetry::Resource::Detector::Container : nil),
+        'azure' => (defined?(::OpenTelemetry::Resource::Detector::Azure) ? ::OpenTelemetry::Resource::Detector::Azure : nil),
+        'aws' => (defined?(::OpenTelemetry::Resource::Detector::AWS) ? ::OpenTelemetry::Resource::Detector::AWS : nil)
+      }
+
+      ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s.split(',').map(&:strip).reject(&:empty?).reduce(::OpenTelemetry::SDK::Resources::Resource.create({})) do |resource, detector|
+        detector_class = resource_map[detector]
+        detector_class ? resource.merge(detector_class.detect) : resource
+      end
+    end


Would it make sense to move this into the resource detectors, ie if disabled return empty resource. This way they benefit & the logic here is simplified as well as ease of adding more resource detectors.

Do you mean adding disable logic in each resource detector?

Currently there is no env var from specification that can disable individual resource detectors.

OTEL_RUBY_RESOURCE_DETECTORS is only used for the operator and for ease-of-use (i.e. this idea is from js-contrib).

Correct I am suggesting add it in the detectors with a default state of enabled. only if the env variable is present and the detector not listed is it disabled that way we avoid the maps/lookup process.

kaylareopelle · 2026-05-13T23:19:52Z

We chatted about this during the SIG on 12 May 2026. I'm going to look into what it takes to put this in a new repository and whether we can move this PR with all its history and conversation to a possible new repository. Holding off on merging until I learn about the repository options.

If anyone is opposed to the idea of putting this work in a separate repository, please let me know.

thompson-tomo · 2026-05-14T02:27:50Z

I like the idea of having a 3rd repo. My suggestion would be either opentelemetry-ruby-distro (my preference) or maybe opentelemetry-ruby-releases. This would follow the php example https://github.com/open-telemetry/opentelemetry-php-distro.

Within the new repo we could also put the all instrumentation gem & the rails instrumentation gem. That would help us to streamline our release process as it would eliminate the need to be manually bumping dependencies during the release process and instead we can rely on renovate.

My impression is that we will need to merge this PR into contrib and when the new repo is created it is a clone of this repo with the history filtered based on paths. A similar thing was done to split semantic conventions.

My main suggestion for this PR would be to:

rename the root folder to auto_instrumentation which would enable us to potentially down the track to have multiple auto instrumentation variants ie aws.
name this gem auto_instrumentation-all or contrib that way name makes it clear what is included.

This gives us a structure which can grow to include other distro types ie Faas to ensure they are actively maintained etc as well as achieve consistency.

thompson-tomo · 2026-05-20T01:37:02Z

For reference this third repo pattern could address release pr errors we see in #2358

xuan-cao-swi · 2026-06-29T18:03:47Z

Moved to https://github.com/open-telemetry/opentelemetry-ruby-instrumentation

xuan-cao-swi added 8 commits January 29, 2025 14:59

feat: init commit for zero-code instrumentation

9d13c5a

lint

444959a

rubocop

4c0c97b

enforce the dependencies version

8a2fadd

assume use bundle exec all the time

f96a637

merge

ef5f348

update readme

60a3ab2

cspell

3512225

xuan-cao-swi marked this pull request as ready for review February 26, 2025 19:13

xuan-cao-swi requested review from ahayworth, arielvalentin, dazuma, ericmustin, fbogsany, kaylareopelle, mwear, plantfansam, robbkidd, robertlaurin and simi as code owners February 26, 2025 19:13

xuan-cao-swi requested review from a team February 26, 2025 19:13

xuan-cao-swi mentioned this pull request Mar 3, 2025

Autoinstrumentation for opentelemetry ruby open-telemetry/opentelemetry-operator#3762

Open

github-actions Bot added the stale Marks an issue/PR stale label Mar 29, 2025

kaylareopelle removed the stale Marks an issue/PR stale label Apr 2, 2025

update the script

2c880da

github-actions Bot added the stale Marks an issue/PR stale label May 3, 2025

xuan-cao-swi and others added 3 commits April 22, 2026 12:20

merge

d282844

Add auto-instrumentation configuration to labeler

14727c2

simplecov

91dde11

thompson-tomo reviewed Apr 23, 2026

View reviewed changes

coverage

4c00f64

thompson-tomo mentioned this pull request Apr 23, 2026

Telemetry.sdk.* attributes not automatically added to resource open-telemetry/opentelemetry-ruby#2109

Closed

arielvalentin reviewed Apr 27, 2026

View reviewed changes

xuan-cao-swi and others added 7 commits April 28, 2026 10:04

Merge branch 'open-telemetry:main' into auto-instrumentation

0327894

additional resource attr

b931e47

Merge branch 'auto-instrumentation' of github.com:xuan-cao-swi/opente…

91818b5

…lemetry-ruby-contrib into auto-instrumentation

use warn and registry

963e81f

revision

26b53d0

Merge branch 'main' into auto-instrumentation

4cbdf9e

Merge branch 'main' into auto-instrumentation

4f2a2ed

thompson-tomo reviewed May 3, 2026

View reviewed changes

xuan-cao-swi and others added 4 commits May 5, 2026 12:00

Merge branch 'main' into auto-instrumentation

cecec62

update

62f4781

bypass jruby test

4e76f91

bypass jruby test

cf34a29

kaylareopelle approved these changes May 5, 2026

View reviewed changes

panicboat mentioned this pull request May 17, 2026

docs(superpowers): preempt #25 monolith OTel to Operator native panicboat/platform#425

Merged

3 tasks

Simplify Rakefile by removing YARD task options

48a635d

kaylareopelle mentioned this pull request Jun 1, 2026

Request for new repository: opentelemetry-ruby-instrumentation open-telemetry/community#3494

Closed

xuan-cao-swi mentioned this pull request Jun 3, 2026

feat: add auto instrumentation component open-telemetry/opentelemetry-ruby-instrumentation#2

Closed

xuan-cao-swi closed this Jun 29, 2026

-resource_detectors = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s
+resource_detectors = ENV['OTEL_RUBY_RESOURCE_DETECTORS'].to_s.split(',').map(&:strip)
+require 'opentelemetry-resource-detector-container' if resource_detectors.include?('container')
+require 'opentelemetry-resource-detector-azure' if resource_detectors.include?('azure')
+require 'opentelemetry-resource-detector-aws' if resource_detectors.include?('aws')

Uh oh!

Conversation

xuan-cao-swi commented Jan 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

xuan-cao-swi commented Feb 26, 2025

Uh oh!

github-actions Bot commented Mar 29, 2025

Uh oh!

github-actions Bot commented May 3, 2025

Uh oh!

thompson-tomo commented Apr 22, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

arielvalentin left a comment

Choose a reason for hiding this comment

Thread Safety

Hardcoded Instrumentation Map

Code Coverage

✅ What I liked

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaylareopelle May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

kaylareopelle commented May 13, 2026

Uh oh!

thompson-tomo commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thompson-tomo commented May 20, 2026

xuan-cao-swi commented Jan 30, 2025 •

edited

Loading

thompson-tomo Apr 23, 2026 •

edited

Loading

kaylareopelle May 5, 2026 •

edited

Loading

thompson-tomo commented May 14, 2026 •

edited

Loading