feat: HTTPClient semantic convention stability migration (#1588)

* feat: HTTPClient semantic convention stability migration

* fix: test update

---------

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

Author: hannahramadan

instrumentation/http_client/Appraisals

@@ -4,6 +4,15 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-appraise 'httpclient-2.8' do
-  gem 'httpclient', '~> 2.8.0'
+# 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/
+
+semconv_stability = %w[dup stable old]
+
+semconv_stability.each do |mode|
+  appraise "httpclient-2.8-#{mode}" do
+    gem 'httpclient', '~> 2.8.0'
+  end
 end

instrumentation/http_client/README.md

@@ -52,3 +52,19 @@ The `opentelemetry-instrumentation-http_client` gem is distributed under the Apa
 [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 HttpClient 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, HttpClient instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to HttpClient 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/http_client/lib/opentelemetry/instrumentation/http_client/instrumentation.rb

@@ -12,8 +12,9 @@ module HttpClient
       # The Instrumentation class contains logic to detect and install the HttpClient instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         install do |_config|
-          require_dependencies
-          patch
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
+          send(:"patch_#{patch_type}")
         end
 
         present do
@@ -22,14 +23,47 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
 
         private
 
-        def patch
-          ::HTTPClient.prepend(Patches::Client)
-          ::HTTPClient::Session.prepend(Patches::Session)
+        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 patch_dup
+          ::HTTPClient.prepend(Patches::Dup::Client)
+          ::HTTPClient::Session.prepend(Patches::Dup::Session)
+        end
+
+        def patch_old
+          ::HTTPClient.prepend(Patches::Old::Client)
+          ::HTTPClient::Session.prepend(Patches::Old::Session)
+        end
+
+        def patch_stable
+          ::HTTPClient.prepend(Patches::Stable::Client)
+          ::HTTPClient::Session.prepend(Patches::Stable::Session)
+        end
+
+        def require_dependencies_dup
+          require_relative 'patches/dup/client'
+          require_relative 'patches/dup/session'
+        end
+
+        def require_dependencies_old
+          require_relative 'patches/old/client'
+          require_relative 'patches/old/session'
         end
 
-        def require_dependencies
-          require_relative 'patches/client'
-          require_relative 'patches/session'
+        def require_dependencies_stable
+          require_relative 'patches/stable/client'
+          require_relative 'patches/stable/session'
         end
       end
     end

instrumentation/http_client/lib/opentelemetry/instrumentation/http_client/patches/client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module HttpClient
+      module Patches
+        module Dup
+          # Module to prepend to HTTPClient for instrumentation
+          module Client
+            # Constant for the HTTP status range
+            HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+            private
+
+            def do_get_block(req, proxy, conn, &)
+              uri = req.header.request_uri
+              url = "#{uri.scheme}://#{uri.host}"
+              request_method = req.header.request_method
+
+              attributes = {
+                'http.method' => request_method,
+                'http.scheme' => uri.scheme,
+                'http.target' => uri.path,
+                'http.url' => url,
+                'net.peer.name' => uri.host,
+                'net.peer.port' => uri.port,
+                # stable semantic conventions
+                'http.request.method' => request_method,
+                'url.scheme' => uri.scheme,
+                'url.path' => uri.path,
+                'url.full' => url,
+                'server.address' => uri.host,
+                'server.port' => uri.port
+              }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+
+              attributes['url.query'] = uri.query unless uri.query.nil?
+
+              tracer.in_span(request_method, attributes: attributes, kind: :client) do |span|
+                OpenTelemetry.propagation.inject(req.header)
+                super.tap do
+                  response = conn.pop
+                  annotate_span_with_response!(span, response)
+                  conn.push response
+                end
+              end
+            end
+
+            def annotate_span_with_response!(span, response)
+              return unless response&.status_code
+
+              status_code = response.status_code.to_i
+
+              span.set_attribute('http.status_code', status_code)
+              span.set_attribute('http.response.status_code', status_code)
+              span.status = OpenTelemetry::Trace::Status.error unless HTTP_STATUS_SUCCESS_RANGE.cover?(status_code)
+            end
+
+            def tracer
+              HttpClient::Instrumentation.instance.tracer
+            end
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/http_client/lib/opentelemetry/instrumentation/http_client/patches/dup/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module HttpClient
+      module Patches
+        module Dup
+          # Module to prepend to HTTPClient::Session for instrumentation
+          module Session
+            def connect
+              site = @proxy || @dest
+              url = site.addr
+
+              attributes = { 'http.url' => url, 'url.full' => url }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+              tracer.in_span('CONNECT', attributes: attributes) do
+                super
+              end
+            end
+
+            private
+
+            def tracer
+              HttpClient::Instrumentation.instance.tracer
+            end
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/http_client/lib/opentelemetry/instrumentation/http_client/patches/dup/session.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module HttpClient
+      module Patches
+        module Old
+          # Module to prepend to HTTPClient for instrumentation
+          module Client
+            # Constant for the HTTP status range
+            HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+            private
+
+            def do_get_block(req, proxy, conn, &)
+              uri = req.header.request_uri
+              url = "#{uri.scheme}://#{uri.host}"
+              request_method = req.header.request_method
+
+              attributes = {
+                'http.method' => request_method,
+                'http.scheme' => uri.scheme,
+                'http.target' => uri.path,
+                'http.url' => url,
+                'net.peer.name' => uri.host,
+                'net.peer.port' => uri.port
+              }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+
+              tracer.in_span("HTTP #{request_method}", attributes: attributes, kind: :client) do |span|
+                OpenTelemetry.propagation.inject(req.header)
+                super.tap do
+                  response = conn.pop
+                  annotate_span_with_response!(span, response)
+                  conn.push response
+                end
+              end
+            end
+
+            def annotate_span_with_response!(span, response)
+              return unless response&.status_code
+
+              status_code = response.status_code.to_i
+
+              span.set_attribute('http.status_code', status_code)
+              span.status = OpenTelemetry::Trace::Status.error unless HTTP_STATUS_SUCCESS_RANGE.cover?(status_code)
+            end
+
+            def tracer
+              HttpClient::Instrumentation.instance.tracer
+            end
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/http_client/lib/opentelemetry/instrumentation/http_client/patches/old/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module HttpClient
+      module Patches
+        module Old
+          # Module to prepend to HTTPClient::Session for instrumentation
+          module Session
+            def connect
+              site = @proxy || @dest
+              url = site.addr
+
+              attributes = { 'http.url' => url }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+              tracer.in_span('HTTP CONNECT', attributes: attributes) do
+                super
+              end
+            end
+
+            private
+
+            def tracer
+              HttpClient::Instrumentation.instance.tracer
+            end
+          end
+        end
+      end
+    end
+  end
+end