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

There have been a lot of changes since my last review. Removing my approval to take another look.

…lemetry-ruby-contrib into auto-instrumentation

arielvalentin · 2026-04-09T04:33:39Z

@xuan-cao-swi can you rebase main? I will test this ASAP and get it finished this Friday

arielvalentin

One last set of requests.

.github/workflows/ci-contrib.yml

arielvalentin · 2026-04-09T14:18:55Z

packages/auto-instrumentation/lib/auto-instrumentation.rb

Whenever we patch and introduce methods that are not decorators including class, module, or instance variables we should prefix them with _otel for methods or @_otel for variables.

Any Constants should be marked as private and likely best to prefix with OTEL_ as well.

Updated with prefix and private_constant

thompson-tomo

Can you also add it to the auto labeller config

packages/auto-instrumentation/auto-instrumentation.gemspec

thompson-tomo · 2026-04-09T14:31:26Z

packages/auto-instrumentation/Gemfile

+  gem 'bundler'
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop'
+  gem 'rubocop-performance'
+  gem 'simplecov'
+  gem 'yard'
+  gem 'opentelemetry-test-helpers'


Can you add versions like the others

thompson-tomo · 2026-04-09T14:35:26Z

.cspell.yml

+  - Triager
+  - triagers
+  - Untrace
+  - vitess
+  - webmocks
+  - yardoc
+  - rackup
+  - traceparent


Are we sure all of these are needed, I believe I added some of these to cspell ie yard

I am not sure about what is needed; feel free to suggest which one to remove.

My suggestion would be to remove them all & then see which one's you get warnings for.

Removed these words

Just checking on this one as I can still see them.

thompson-tomo

Do we also need to add it to toys for the release process?

packages/auto-instrumentation/CHANGELOG.md

…trib into auto-instrumentation

Co-authored-by: Ariel Valentin <arielvalentin@users.noreply.github.com> Co-authored-by: James Thompson <thompson.tomo@outlook.com>

…lemetry-ruby-contrib into auto-instrumentation

thompson-tomo

Note we are still needing it to be added to labeller & release process. I have drafted updated docs to help guide this process aka #2219.

thompson-tomo · 2026-04-13T15:47:08Z

packages/auto-instrumentation/.rubocop.yml

+Naming/FileName:
+  Enabled: false
+Gemspec/DevelopmentDependencies:
+  Enabled: false


Suggested change

Naming/FileName:

Enabled: false

Gemspec/DevelopmentDependencies:

Enabled: false

If naming is an issue add an exclusion rather than disable entire cop.

thompson-tomo · 2026-04-13T15:49:36Z

packages/auto-instrumentation/auto-instrumentation.gemspec

+
+  if spec.respond_to?(:metadata)
+    spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+    spec.metadata['source_code_uri'] = 'https://github.com/open-telemetry/opentelemetry-ruby-contrib/auto-instrumentation'


Update to match existing instrumentations ie use tag and directory.

thompson-tomo · 2026-04-13T15:51:28Z

packages/auto-instrumentation/Gemfile

+gemspec
+
+group :test do
+  gem 'bundler'


This should have a version if we in fact need it no other gem list it.

Removed the bundler

…lemetry-ruby-contrib into auto-instrumentation

kaylareopelle

This is so close! I noticed a few things in my review today.

kaylareopelle · 2025-10-31T21:04:56Z

packages/auto-instrumentation/lib/auto-instrumentation.rb

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


Are there any new instrumentations we should add here?

kaylareopelle · 2026-04-14T14:03:05Z

packages/auto-instrumentation/auto-instrumentation.gemspec

+require 'version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'auto-instrumentation'


What do you think about calling the gem opentelemetry-auto-instrumentation? Without the opentelemetry prefix it feels very broad.

I remember talking about naming a long time ago, but haven't found that conversation.

@thompson-tomo made a similar comment in the changelog about updating the name.

kaylareopelle · 2026-04-14T14:08:25Z

packages/auto-instrumentation/README.md

+opentelemetry-instrumentation-all
+opentelemetry-exporter-otlp
+opentelemetry-helpers-mysql
+opentelemetry-helpers-sql-obfuscation


I think we want to replace the sql-obfuscation gem with opentelemetry-helpers-sql-processor

kaylareopelle · 2026-04-14T14:08:59Z

packages/auto-instrumentation/README.md

+opentelemetry-helpers-sql-obfuscation
+opentelemetry-resource-detector-azure
+opentelemetry-resource-detector-container
+opentelemetry-resource-detector-aws


We also have a GCP resource detector. Does that make sense to include?

kaylareopelle · 2026-04-14T14:11:40Z

packages/auto-instrumentation/README.md

+
+## Configuration
+
+The following environment variables are specific to this gem (not standard OpenTelemetry variables):


What do you think about mentioning that all other OTEL environment variables can still be used for configuration with this gem?

kaylareopelle · 2026-04-14T14:27:17Z

packages/auto-instrumentation/test/auto-instrumentation_test.rb

+
+require 'test_helper'
+
+describe 'AutoInstrumentation' do


Suggested change

describe 'AutoInstrumentation' do

describe 'OpenTelemetry::AutoInstrumentation' do

kaylareopelle · 2026-04-14T14:29:54Z

packages/auto-instrumentation/test/test_helper.rb

+require 'opentelemetry-sdk'
+require 'opentelemetry-instrumentation-all'


If we require these and opentelemetry/resource/detector here, could we be getting false positives? (just thinking about open-telemetry/opentelemetry-ruby#1956)

The tests seem to pass even if we remove those requires.

kaylareopelle · 2026-04-14T14:41:35Z

packages/auto-instrumentation/lib/auto-instrumentation.rb

+      warn '[OpenTelemetry] WARNING: Detected OpenTelemetry gems in your Gemfile: ' \
+           "#{gem_names}. When using auto-instrumentation, OpenTelemetry gems are loaded " \
+           'from the auto-instrumentation gem path, NOT from your bundle. The gem versions ' \
+           'in your Gemfile/Gemfile.lock are not used and may cause version conflicts or ' \
+           'unexpected behavior. Please remove these gems from your Gemfile when using ' \
+           'auto-instrumentation.'


Does this mean that people who want to use metrics or logs can't use auto instrumentation? If that's the case, what do you think about adding a note to the README?

kaylareopelle · 2026-04-14T14:55:34Z

packages/auto-instrumentation/example/rails-example/Gemfile

+gem 'rake', '13.0.6'
+gem 'bigdecimal', '3.1.3'
+gem 'logger', '1.5.3'


Why are these versions locked?

This was the main problem I encountered with the rails example. I was using Ruby 3.4 and these versions are older than the latest versions. If I commented these versions out and regenerated the Gemfile.lock, everything worked fine.

When I tried to follow the instructions in the example README and installed the versions it asked for specifically, I kept getting the same error.

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 a team, ahayworth, arielvalentin, dazuma, ericmustin, fbogsany, kaylareopelle, mwear, plantfansam, robbkidd, robertlaurin and simi as code owners 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 requested a review from marcotc February 5, 2026 16:13

Merge branch 'main' into auto-instrumentation

9f15329

kaylareopelle and others added 4 commits March 3, 2026 08:59

Merge branch 'main' into auto-instrumentation

27f77a5

emit warning if user Gemfile contain opentelemetry-related gem

1c43468

Merge branch 'main' into auto-instrumentation

b7f25b4

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

ee878b7

…lemetry-ruby-contrib into auto-instrumentation

Merge branch 'main' into auto-instrumentation

0c58925

github-actions bot added the ci label Apr 9, 2026

xuan-cao-swi requested a review from kaylareopelle April 9, 2026 14:05

Merge branch 'main' into auto-instrumentation

7a5e7e6

arielvalentin reviewed Apr 9, 2026

View reviewed changes

thompson-tomo reviewed Apr 9, 2026

View reviewed changes

packages/auto-instrumentation/CHANGELOG.md Show resolved Hide resolved

xuan-cao-swi and others added 6 commits April 13, 2026 11:10

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

b644d81

…trib into auto-instrumentation

Apply suggestions from code review

608417a

Co-authored-by: Ariel Valentin <arielvalentin@users.noreply.github.com> Co-authored-by: James Thompson <thompson.tomo@outlook.com>

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

bf98eea

…lemetry-ruby-contrib into auto-instrumentation

revision

95958ec

update bundler version

c9b79f3

update bundler version

31ea352

thompson-tomo reviewed Apr 13, 2026

View reviewed changes

xuan-cao-swi and others added 5 commits April 13, 2026 12:44

update

4a15e56

rubocop format

ef6d1d3

Merge branch 'main' into auto-instrumentation

a4c0b64

remove cspell words

74a9bc1

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

01e4f2e

…lemetry-ruby-contrib into auto-instrumentation

kaylareopelle reviewed Apr 14, 2026

View reviewed changes


		## Configuration

		The following environment variables are specific to this gem (not standard OpenTelemetry variables):

	describe 'AutoInstrumentation' do
	describe 'OpenTelemetry::AutoInstrumentation' do

		require 'opentelemetry-sdk'
		require 'opentelemetry-instrumentation-all'

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!

arielvalentin commented Apr 9, 2026

Uh oh!

arielvalentin left a comment

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!

thompson-tomo left a comment

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!

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!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thompson-tomo left a comment • 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!

thompson-tomo Apr 13, 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!

kaylareopelle 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!

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 Jan 30, 2025 •

edited

Loading

thompson-tomo left a comment •

edited

Loading

thompson-tomo Apr 13, 2026 •

edited

Loading