feat: NET::HTTP semantic convention stability migration

Author: hannahramadan

instrumentation/net_http/Appraisals

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.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 "net-http-#{mode}" do
+    # NOOP - net-http is part of the Ruby standard library.
+    # We are only using Appraisals to allow testing of the
+    # different stability modes. The file and the Appraisal
+    # gem can be removed once semconv migration is complete.
+  end
+end

instrumentation/net_http/Gemfile

@@ -9,6 +9,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
+  gem 'appraisal', '~> 2.5'
   gem 'bundler', '~> 2.4'
   gem 'minitest', '~> 5.0'
   gem 'opentelemetry-sdk', '~> 1.1'

instrumentation/net_http/README.md

@@ -52,3 +52,19 @@ Apache 2.0 license. See [LICENSE][license-github] for more information.
 [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 Net::HTTP 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, Net::HTTP instrumentation code comes in three patch versions: `dup`, `old`, and `stable`. These versions are identical except for the attributes they send. Any changes to Net::HTTP 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/net_http/lib/opentelemetry/instrumentation/net/http/instrumentation.rb

@@ -12,8 +12,9 @@ module HTTP
         # 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
@@ -30,12 +31,41 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
 
           private
 
-          def require_dependencies
-            require_relative 'patches/instrumentation'
+          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
-            ::Net::HTTP.prepend(Patches::Instrumentation)
+          def require_dependencies_dup
+            require_relative 'patches/dup/instrumentation'
+          end
+
+          def require_dependencies_old
+            require_relative 'patches/old/instrumentation'
+          end
+
+          def require_dependencies_stable
+            require_relative 'patches/stable/instrumentation'
+          end
+
+          def patch_dup
+            ::Net::HTTP.prepend(Patches::Dup::Instrumentation)
+          end
+
+          def patch_old
+            ::Net::HTTP.prepend(Patches::Old::Instrumentation)
+          end
+
+          def patch_stable
+            ::Net::HTTP.prepend(Patches::Stable::Instrumentation)
           end
         end
       end

instrumentation/net_http/lib/opentelemetry/instrumentation/net/http/patches/dup/instrumentation.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Net
+      module HTTP
+        module Patches
+          module Dup
+            # Module to prepend to Net::HTTP for instrumentation
+            module Instrumentation
+              USE_SSL_TO_SCHEME = { false => 'http', true => 'https' }.freeze
+
+              # Constant for the HTTP status range
+              HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+              def request(req, body = nil, &)
+                # Do not trace recursive call for starting the connection
+                return super unless started?
+
+                return super if untraced?
+
+                attributes = {
+                  OpenTelemetry::SemanticConventions::Trace::HTTP_METHOD => req.method,
+                  OpenTelemetry::SemanticConventions::Trace::HTTP_SCHEME => USE_SSL_TO_SCHEME[use_ssl?],
+                  OpenTelemetry::SemanticConventions::Trace::HTTP_TARGET => req.path,
+                  OpenTelemetry::SemanticConventions::Trace::NET_PEER_NAME => @address,
+                  OpenTelemetry::SemanticConventions::Trace::NET_PEER_PORT => @port,
+                  'http.request.method' => req.method,
+                  'url.scheme' => USE_SSL_TO_SCHEME[use_ssl?],
+                  'server.address' => @address,
+                  'server.port' => @port
+                }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+
+                path, query = split_path_and_query(req.path)
+                attributes['url.path'] = path unless attributes.key?('url.path')
+                attributes['url.query'] = query if query
+
+                tracer.in_span(
+                  req.method,
+                  attributes: attributes,
+                  kind: :client
+                ) do |span|
+                  OpenTelemetry.propagation.inject(req)
+
+                  super.tap do |response|
+                    annotate_span_with_response!(span, response)
+                  end
+                end
+              end
+
+              private
+
+              def connect
+                return super if untraced?
+
+                if proxy?
+                  conn_address = proxy_address
+                  conn_port    = proxy_port
+                else
+                  conn_address = address
+                  conn_port    = port
+                end
+
+                attributes = {
+                  OpenTelemetry::SemanticConventions::Trace::NET_PEER_NAME => conn_address,
+                  OpenTelemetry::SemanticConventions::Trace::NET_PEER_PORT => conn_port,
+                  'server.address' => conn_address,
+                  'server.port' => conn_port
+                }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)
+
+                if use_ssl? && proxy?
+                  span_name = 'CONNECT'
+                  span_kind = :client
+                else
+                  span_name = 'connect'
+                  span_kind = :internal
+                end
+
+                tracer.in_span(span_name, attributes: attributes, kind: span_kind) do
+                  super
+                end
+              end
+
+              def annotate_span_with_response!(span, response)
+                return unless response&.code
+
+                status_code = response.code.to_i
+
+                span.set_attribute(OpenTelemetry::SemanticConventions::Trace::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
+                Net::HTTP::Instrumentation.instance.tracer
+              end
+
+              def untraced?
+                untraced_context? || untraced_host?
+              end
+
+              def untraced_host?
+                return true if Net::HTTP::Instrumentation.instance.config[:untraced_hosts]&.any? do |host|
+                  host.is_a?(Regexp) ? host.match?(@address) : host == @address
+                end
+
+                false
+              end
+
+              def untraced_context?
+                OpenTelemetry::Common::Utilities.untraced?
+              end
+
+              def split_path_and_query(path)
+                path_and_query = path.split('?')
+
+                [path_and_query[0], path_and_query[1]]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end