feat: HTTP semantic convention stability migration

Author: hannahramadan

instrumentation/ethon/Appraisals

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
-appraise 'ethon-0.16' do
-  gem 'ethon', '~> 0.16.0'
-end
+# To faclitate HTTP semantic convention stability migration, we are using
+# appraisal to test the different semantic convention modes along with different
+# 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 "ethon-0.16.0-#{mode}" do
+    gem 'ethon', '~> 0.16.0'
+  end
 
-appraise 'ethon-latest' do
-  gem 'ethon'
+  appraise "ethon-#{mode}" do
+    gem 'ethon'
+  end
 end

instrumentation/ethon/README.md

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

@@ -11,8 +11,9 @@ module Ethon
       # instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         install do |_config|
-          require_dependencies
-          add_patches
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
+          send(:"add_patches_#{patch_type}")
         end
 
         present do
@@ -23,13 +24,46 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
 
         private
 
-        def require_dependencies
-          require_relative 'patches/easy'
+        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_dup
+          require_relative 'patches/dup/easy'
+          require_relative 'patches/multi'
+        end
+
+        def require_dependencies_stable
+          require_relative 'patches/stable/easy'
           require_relative 'patches/multi'
         end
 
-        def add_patches
-          ::Ethon::Easy.prepend(Patches::Easy)
+        def require_dependencies_old
+          require_relative 'patches/old/easy'
+          require_relative 'patches/multi'
+        end
+
+        def add_patches_dup
+          ::Ethon::Easy.prepend(Patches::Dup::Easy)
+          ::Ethon::Multi.prepend(Patches::Multi)
+        end
+
+        def add_patches_stable
+          ::Ethon::Easy.prepend(Patches::Stable::Easy)
+          ::Ethon::Multi.prepend(Patches::Multi)
+        end
+
+        def add_patches_old
+          ::Ethon::Easy.prepend(Patches::Old::Easy)
           ::Ethon::Multi.prepend(Patches::Multi)
         end
       end

instrumentation/ethon/lib/opentelemetry/instrumentation/ethon/patches/dup/easy.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Ethon
+      module Patches
+        # Module using old and stable HTTP semantic conventions
+        module Dup
+          # Ethon::Easy patch for instrumentation
+          module Easy
+            ACTION_NAMES_TO_HTTP_METHODS = Hash.new do |h, k|
+              # #to_s is required because user input could be symbol or string
+              h[k] = k.to_s.upcase
+            end
+            HTTP_METHODS_TO_SPAN_NAMES = Hash.new { |h, k| h[k] = "HTTP #{k}" }
+
+            # Constant for the HTTP status range
+            HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+            def http_request(url, action_name, options = {})
+              @otel_method = ACTION_NAMES_TO_HTTP_METHODS[action_name]
+              super
+            end
+
+            def headers=(headers)
+              # Store headers to call this method again when span is ready
+              @otel_original_headers = headers
+              super
+            end
+
+            def perform
+              otel_before_request
+              super
+            end
+
+            def complete
+              begin
+                response_options = mirror.options
+                response_code = (response_options[:response_code] || response_options[:code]).to_i
+                if response_code.zero?
+                  return_code = response_options[:return_code]
+                  message = return_code ? ::Ethon::Curl.easy_strerror(return_code) : 'unknown reason'
+                  @otel_span.status = OpenTelemetry::Trace::Status.error("Request has failed: #{message}")
+                else
+                  @otel_span.set_attribute('http.status_code', response_code)
+                  @otel_span.set_attribute('http.response.status_code', response_code)
+                  @otel_span.status = OpenTelemetry::Trace::Status.error unless HTTP_STATUS_SUCCESS_RANGE.cover?(response_code.to_i)
+                end
+              ensure
+                @otel_span&.finish
+                @otel_span = nil
+              end
+              super
+            end
+
+            def reset
+              super
+            ensure
+              @otel_span = nil
+              @otel_method = nil
+              @otel_original_headers = nil
+            end
+
+            def otel_before_request
+              method = 'N/A' # Could be GET or not HTTP at all
+              method = @otel_method if instance_variable_defined?(:@otel_method) && !@otel_method.nil?
+
+              @otel_span = tracer.start_span(
+                HTTP_METHODS_TO_SPAN_NAMES[method],
+                attributes: span_creation_attributes(method),
+                kind: :client
+              )
+
+              @otel_original_headers ||= {}
+              OpenTelemetry::Trace.with_span(@otel_span) do
+                OpenTelemetry.propagation.inject(@otel_original_headers)
+              end
+              self.headers = @otel_original_headers
+            end
+
+            def otel_span_started?
+              instance_variable_defined?(:@otel_span) && !@otel_span.nil?
+            end
+
+            private
+
+            def span_creation_attributes(method)
+              instrumentation_attrs = {
+                'http.method' => method,
+                'http.request.method' => method
+              }
+
+              uri = _otel_cleanse_uri(url)
+              if uri
+                instrumentation_attrs['http.url'] = uri.to_s
+                instrumentation_attrs['url.full'] = uri.to_s
+                instrumentation_attrs['net.peer.name'] = uri.host if uri.host
+                instrumentation_attrs['server.address'] = uri.host if uri.host
+              end
+
+              config = Ethon::Instrumentation.instance.config
+              instrumentation_attrs['peer.service'] = config[:peer_service] if config[:peer_service]
+              instrumentation_attrs.merge!(
+                OpenTelemetry::Common::HTTP::ClientContext.attributes
+              )
+            end
+
+            # Returns a URL string with userinfo removed.
+            #
+            # @param [String] url The URL string to cleanse.
+            #
+            # @return [String] the cleansed URL.
+            def _otel_cleanse_uri(url)
+              cleansed_url = URI.parse(url)
+              cleansed_url.password = nil
+              cleansed_url.user = nil
+              cleansed_url
+            rescue URI::Error
+              nil
+            end
+
+            def tracer
+              Ethon::Instrumentation.instance.tracer
+            end
+          end
+        end
+      end
+    end
+  end
+end