feat: Rack semantic stability opt in

instrumentation/CONTRIBUTING.md

@@ -458,8 +458,11 @@ end
 # Set up fake Rack application
 builder = Rack::Builder.app do
   # Integration is automatic in web frameworks but plain Rack applications require this line.
+  # - middleware_args_old to emit old HTTP semantic conventions
+  # - middleware_args_stable to emit stable HTTP semantic conventions
+  # - middleware_args_dup to emit both old and stable HTTP semantic conventions
   # Enable it in your config.ru.
-  use *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args
+  use *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_old
   run ExampleAPI
 end
 app = Rack::MockRequest.new(builder)

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

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

instrumentation/grape/example/trace_demonstration.rb

@@ -43,8 +43,11 @@ class ExampleAPI < Grape::API
 # Set up fake Rack application
 builder = Rack::Builder.app do
   # Integration is automatic in web frameworks but plain Rack applications require this line.
+  # - middleware_args_old to emit old HTTP semantic conventions
+  # - middleware_args_stable to emit stable HTTP semantic conventions
+  # - middleware_args_dup to emit both old and stable HTTP semantic conventions
   # Enable it in your config.ru.
-  use *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args
+  use *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_old
   run ExampleAPI
 end
 app = Rack::MockRequest.new(builder)

instrumentation/grape/test/test_helper.rb

@@ -41,7 +41,17 @@ def unsubscribe
 
 def build_rack_app(api_class)
   builder = Rack::Builder.app do
-    use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
+    stability_opt_in = ENV.fetch('OTEL_SEMCONV_STABILITY_OPT_IN', '')
+    values = stability_opt_in.split(',').map(&:strip)
+
+    if values.include?('http/dup')
+      use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_dup)
+    elsif values.include?('http')
+      use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_stable)
+    else
+      use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args_old)
+    end
+
     run api_class
   end
   Rack::MockRequest.new(builder)

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
@@ -35,23 +36,62 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         #
         # @example Default usage
         #   Rack::Builder.new do
-        #     use *OpenTelemetry::Instrumentation::Rack::Instrumenation.instance.middleware_args
+        #     use *OpenTelemetry::Instrumentation::Rack::Instrumenation.instance.middleware_args_old
         #     run lambda { |_arg| [200, { 'Content-Type' => 'text/plain' }, body] }
         #   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]]
+        def middleware_args_old
+          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
+
+        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)