feat: Rack semantic stability opt in (#1594)

* feat: Rack semantic stability opt in

* fix: add readme and rubocop fix

* fix: rubocp edits

* Apply suggestions from code review

Co-authored-by: Kayla Reopelle <[email protected]>

* Fix: Add Sinatra documentation & small refactor

* Fix: spelling

* Fix: refactors

* Test middleware_args_*

* Fix: rubocop

* Sinatra testing

* rubocop

* alias middleware_args middleware_args_old

* appease rubocop

* revert grape changes

* Update action_pack to use middleware alias

* Rely on Rack semconv middlware alias for Sinatra instrumentation

* Update action_pack changelog

---------

Co-authored-by: Kayla Reopelle <[email protected]>

Author: hannahramadan

instrumentation/action_pack/README.md

@@ -89,3 +89,21 @@ The `opentelemetry-instrumentation-action_pack` gem is distributed under the Apa
 [slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
 [rails-home]: https://rubyonrails.org/
+
+## HTTP semantic convention stability
+
+In the OpenTelemetry ecosystem, HTTP semantic conventions have now reached a stable state. However, the initial Rack instrumentation, which Action Pack relies on, was introduced before this stability was achieved, which resulted in HTTP attributes being based on an older version of the semantic conventions.
+
+To facilitate the migration to stable semantic conventions, you can use the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. This variable allows you to opt-in to the new stable conventions, ensuring compatibility and future-proofing your instrumentation.
+
+Sinatra instrumentation installs Rack middleware, but the middleware version it installs depends on which `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable is set.
+
+When setting the value for `OTEL_SEMCONV_STABILITY_OPT_IN`, you can specify which conventions you wish to adopt:
+
+- `http` - Emits the stable HTTP and networking conventions and ceases emitting the old conventions previously emitted by the instrumentation.
+- `http/dup` - Emits both the old and stable HTTP and networking conventions, enabling a phased rollout of the stable semantic conventions.
+- Default behavior (in the absence of either value) is to continue emitting the old HTTP and networking conventions the instrumentation previously emitted.
+
+During the transition from old to stable conventions, Rack instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to Rack instrumentation should consider all three patches.
+
+For additional information on migration, please refer to our [documentation](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/).

instrumentation/action_pack/lib/opentelemetry/instrumentation/action_pack/railtie.rb

@@ -12,9 +12,20 @@ class Railtie < ::Rails::Railtie
         config.before_initialize do |app|
           OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.install({})
 
+          stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', '')
+          values = stability_opt_in.split(',').map(&:strip)
+
+          rack_middleware_args = if values.include?('http/dup')
+                                   OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_dup
+                                 elsif values.include?('http')
+                                   OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_stable
+                                 else
+                                   OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args
+                                 end
+
           app.middleware.insert_before(
             0,
-            *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args
+            *rack_middleware_args
           )
         end
       end

instrumentation/rack/Appraisals

@@ -4,22 +4,31 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-appraise 'rack-latest' do
-  gem 'rack'
-end
+# To faclitate HTTP semantic convention stability migration, we are using
+# appraisal to test the different semantic convention modes along with different
+# HTTP gem versions. For more information on the semantic convention modes, see:
+# https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
 
-appraise 'rack-3.0' do
-  gem 'rack', '~> 3.0.0'
-end
+semconv_stability = %w[stable old dup]
 
-appraise 'rack-2.2.x' do
-  gem 'rack', '~> 2.2.0'
-end
+semconv_stability.each do |mode|
+  appraise "rack-latest-#{mode}" do
+    gem 'rack'
+  end
 
-appraise 'rack-2.1' do
-  gem 'rack', '~> 2.1.2'
-end
+  appraise "rack-3.0-#{mode}" do
+    gem 'rack', '~> 3.0.0'
+  end
+
+  appraise "rack-2.2.x-#{mode}" do
+    gem 'rack', '~> 2.2.0'
+  end
+
+  appraise "rack-2.1-#{mode}" do
+    gem 'rack', '~> 2.1.2'
+  end
 
-appraise 'rack-2.0' do
-  gem 'rack', '~> 2.0.8'
+  appraise "rack-2.0-#{mode}" do
+    gem 'rack', '~> 2.0.8'
+  end
 end

instrumentation/rack/README.md

@@ -101,3 +101,19 @@ The `opentelemetry-instrumentation-rack` gem is distributed under the Apache 2.0
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
 [slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
+
+## HTTP semantic convention stability
+
+In the OpenTelemetry ecosystem, HTTP semantic conventions have now reached a stable state. However, the initial Rack instrumentation was introduced before this stability was achieved, which resulted in HTTP attributes being based on an older version of the semantic conventions.
+
+To facilitate the migration to stable semantic conventions, you can use the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. This variable allows you to opt-in to the new stable conventions, ensuring compatibility and future-proofing your instrumentation.
+
+When setting the value for `OTEL_SEMCONV_STABILITY_OPT_IN`, you can specify which conventions you wish to adopt:
+
+- `http` - Emits the stable HTTP and networking conventions and ceases emitting the old conventions previously emitted by the instrumentation.
+- `http/dup` - Emits both the old and stable HTTP and networking conventions, enabling a phased rollout of the stable semantic conventions.
+- Default behavior (in the absence of either value) is to continue emitting the old HTTP and networking conventions the instrumentation previously emitted.
+
+During the transition from old to stable conventions, Rack instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to Rack instrumentation should consider all three patches.
+
+For additional information on migration, please refer to our [documentation](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/).

instrumentation/rack/lib/opentelemetry/instrumentation/rack/instrumentation.rb

@@ -13,7 +13,8 @@ module Rack
       # instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         install do |_config|
-          require_dependencies
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
         end
 
         present do
@@ -40,18 +41,59 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         #   end
         # @return [Array] consisting of a middleware and arguments used in rack builders
         def middleware_args
-          if config.fetch(:use_rack_events, false) == true && defined?(OpenTelemetry::Instrumentation::Rack::Middlewares::EventHandler)
-            [::Rack::Events, [OpenTelemetry::Instrumentation::Rack::Middlewares::EventHandler.new]]
+          if config.fetch(:use_rack_events, false) == true && defined?(OpenTelemetry::Instrumentation::Rack::Middlewares::Old::EventHandler)
+            [::Rack::Events, [OpenTelemetry::Instrumentation::Rack::Middlewares::Old::EventHandler.new]]
           else
-            [OpenTelemetry::Instrumentation::Rack::Middlewares::TracerMiddleware]
+            [OpenTelemetry::Instrumentation::Rack::Middlewares::Old::TracerMiddleware]
+          end
+        end
+
+        alias middleware_args_old middleware_args
+
+        def middleware_args_dup
+          if config.fetch(:use_rack_events, false) == true && defined?(OpenTelemetry::Instrumentation::Rack::Middlewares::Dup::EventHandler)
+            [::Rack::Events, [OpenTelemetry::Instrumentation::Rack::Middlewares::Dup::EventHandler.new]]
+          else
+            [OpenTelemetry::Instrumentation::Rack::Middlewares::Dup::TracerMiddleware]
+          end
+        end
+
+        def middleware_args_stable
+          if config.fetch(:use_rack_events, false) == true && defined?(OpenTelemetry::Instrumentation::Rack::Middlewares::Stable::EventHandler)
+            [::Rack::Events, [OpenTelemetry::Instrumentation::Rack::Middlewares::Stable::EventHandler.new]]
+          else
+            [OpenTelemetry::Instrumentation::Rack::Middlewares::Stable::TracerMiddleware]
           end
         end
 
         private
 
-        def require_dependencies
-          require_relative 'middlewares/event_handler' if defined?(::Rack::Events)
-          require_relative 'middlewares/tracer_middleware'
+        def determine_semconv
+          stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', '')
+          values = stability_opt_in.split(',').map(&:strip)
+
+          if values.include?('http/dup')
+            'dup'
+          elsif values.include?('http')
+            'stable'
+          else
+            'old'
+          end
+        end
+
+        def require_dependencies_old
+          require_relative 'middlewares/old/event_handler' if defined?(::Rack::Events)
+          require_relative 'middlewares/old/tracer_middleware'
+        end
+
+        def require_dependencies_stable
+          require_relative 'middlewares/stable/event_handler' if defined?(::Rack::Events)
+          require_relative 'middlewares/stable/tracer_middleware'
+        end
+
+        def require_dependencies_dup
+          require_relative 'middlewares/dup/event_handler' if defined?(::Rack::Events)
+          require_relative 'middlewares/dup/tracer_middleware'
         end
 
         def config_options(user_config)