feat: Faraday semantic convention stability opt in

instrumentation/faraday/Appraisals

@@ -4,12 +4,22 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-%w[1.0 2.0].each do |version|
-  appraise "faraday-#{version}" do
-    gem 'faraday', "~> #{version}"
+# 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/
+
+versions = %w[1.0 2.0]
+semconv_stability = %w[old stable dup]
+
+semconv_stability.each do |mode|
+  versions.each do |version|
+    appraise "faraday-#{version}-#{mode}" do
+      gem 'faraday', "~> #{version}"
+    end
   end
-end
 
-appraise 'faraday-latest' do
-  gem 'faraday'
+  appraise "faraday-latest-#{mode}" do
+    gem 'faraday'
+  end
 end

instrumentation/faraday/README.md

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

@@ -13,9 +13,10 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         MINIMUM_VERSION = Gem::Version.new('1.0')
 
         install do |_config|
-          require_dependencies
-          register_tracer_middleware
-          use_middleware_by_default
+          patch_type = determine_semconv
+          send(:"require_dependencies_#{patch_type}")
+          send(:"register_tracer_middleware_#{patch_type}")
+          send(:"use_middleware_by_default_#{patch_type}")
         end
 
         compatible do
@@ -36,19 +37,62 @@ def gem_version
           Gem::Version.new(::Faraday::VERSION)
         end
 
-        def require_dependencies
-          require_relative 'middlewares/tracer_middleware'
-          require_relative 'patches/connection'
+        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 'middlewares/dup/tracer_middleware'
+          require_relative 'patches/dup/connection'
+        end
+
+        def require_dependencies_old
+          require_relative 'middlewares/old/tracer_middleware'
+          require_relative 'patches/old/connection'
         end
 
-        def register_tracer_middleware
+        def require_dependencies_stable
+          require_relative 'middlewares/stable/tracer_middleware'
+          require_relative 'patches/stable/connection'
+        end
+
+        def register_tracer_middleware_dup
           ::Faraday::Middleware.register_middleware(
-            open_telemetry: Middlewares::TracerMiddleware
+            open_telemetry: Middlewares::Dup::TracerMiddleware
           )
         end
 
-        def use_middleware_by_default
-          ::Faraday::Connection.prepend(Patches::Connection)
+        def register_tracer_middleware_old
+          ::Faraday::Middleware.register_middleware(
+            open_telemetry: Middlewares::Old::TracerMiddleware
+          )
+        end
+
+        def register_tracer_middleware_stable
+          ::Faraday::Middleware.register_middleware(
+            open_telemetry: Middlewares::Stable::TracerMiddleware
+          )
+        end
+
+        def use_middleware_by_default_dup
+          ::Faraday::Connection.prepend(Patches::Dup::Connection)
+        end
+
+        def use_middleware_by_default_old
+          ::Faraday::Connection.prepend(Patches::Old::Connection)
+        end
+
+        def use_middleware_by_default_stable
+          ::Faraday::Connection.prepend(Patches::Stable::Connection)
         end
       end
     end

instrumentation/faraday/lib/opentelemetry/instrumentation/faraday/middlewares/dup/tracer_middleware.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Faraday
+      module Middlewares
+        module Dup
+          # TracerMiddleware propagates context and instruments Faraday requests
+          # by way of its middleware system
+          class TracerMiddleware < ::Faraday::Middleware
+            HTTP_METHODS_SYMBOL_TO_STRING = {
+              connect: 'CONNECT',
+              delete: 'DELETE',
+              get: 'GET',
+              head: 'HEAD',
+              options: 'OPTIONS',
+              patch: 'PATCH',
+              post: 'POST',
+              put: 'PUT',
+              trace: 'TRACE'
+            }.freeze
+
+            # Constant for the HTTP status range
+            HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+            def call(env)
+              http_method = HTTP_METHODS_SYMBOL_TO_STRING[env.method]
+              config = Faraday::Instrumentation.instance.config
+
+              attributes = span_creation_attributes(
+                http_method: http_method, url: env.url, config: config
+              )
+
+              OpenTelemetry::Common::HTTP::ClientContext.with_attributes(attributes) do |attrs, _|
+                tracer.in_span(
+                  http_method, attributes: attrs, kind: config.fetch(:span_kind)
+                ) do |span|
+                  OpenTelemetry.propagation.inject(env.request_headers)
+
+                  if config[:enable_internal_instrumentation] == false
+                    OpenTelemetry::Common::Utilities.untraced do
+                      app.call(env).on_complete { |resp| trace_response(span, resp.status) }
+                    end
+                  else
+                    app.call(env).on_complete { |resp| trace_response(span, resp.status) }
+                  end
+                rescue ::Faraday::Error => e
+                  trace_response(span, e.response[:status]) if e.response
+
+                  raise
+                end
+              end
+            end
+
+            private
+
+            def span_creation_attributes(http_method:, url:, config:)
+              cleansed_url = OpenTelemetry::Common::Utilities.cleanse_url(url.to_s)
+              attrs = {
+                'http.method' => http_method,
+                'http.request.method' => http_method,
+                'http.url' => cleansed_url,
+                'url.full' => cleansed_url,
+                'faraday.adapter.name' => app.class.name
+              }
+              if url.host
+                attrs['net.peer.name'] = url.host
+                attrs['server.address'] = url.host
+              end
+              attrs['peer.service'] = config[:peer_service] if config[:peer_service]
+
+              attrs.merge!(
+                OpenTelemetry::Common::HTTP::ClientContext.attributes
+              )
+            end
+
+            # Versions prior to 1.0 do not define an accessor for app
+            attr_reader :app if Gem::Version.new(Faraday::VERSION) < Gem::Version.new('1.0.0')
+
+            def tracer
+              Faraday::Instrumentation.instance.tracer
+            end
+
+            def trace_response(span, status)
+              span.set_attribute('http.status_code', status)
+              span.set_attribute('http.response.status_code', status)
+              span.status = OpenTelemetry::Trace::Status.error unless HTTP_STATUS_SUCCESS_RANGE.cover?(status.to_i)
+            end
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/faraday/lib/opentelemetry/instrumentation/faraday/middlewares/old/tracer_middleware.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Faraday
+      module Middlewares
+        module Old
+          # TracerMiddleware propagates context and instruments Faraday requests
+          # by way of its middleware system
+          class TracerMiddleware < ::Faraday::Middleware
+            HTTP_METHODS_SYMBOL_TO_STRING = {
+              connect: 'CONNECT',
+              delete: 'DELETE',
+              get: 'GET',
+              head: 'HEAD',
+              options: 'OPTIONS',
+              patch: 'PATCH',
+              post: 'POST',
+              put: 'PUT',
+              trace: 'TRACE'
+            }.freeze
+
+            # Constant for the HTTP status range
+            HTTP_STATUS_SUCCESS_RANGE = (100..399)
+
+            def call(env)
+              http_method = HTTP_METHODS_SYMBOL_TO_STRING[env.method]
+              config = Faraday::Instrumentation.instance.config
+
+              attributes = span_creation_attributes(
+                http_method: http_method, url: env.url, config: config
+              )
+
+              OpenTelemetry::Common::HTTP::ClientContext.with_attributes(attributes) do |attrs, _|
+                tracer.in_span(
+                  "HTTP #{http_method}", attributes: attrs, kind: config.fetch(:span_kind)
+                ) do |span|
+                  OpenTelemetry.propagation.inject(env.request_headers)
+
+                  if config[:enable_internal_instrumentation] == false
+                    OpenTelemetry::Common::Utilities.untraced do
+                      app.call(env).on_complete { |resp| trace_response(span, resp.status) }
+                    end
+                  else
+                    app.call(env).on_complete { |resp| trace_response(span, resp.status) }
+                  end
+                rescue ::Faraday::Error => e
+                  trace_response(span, e.response[:status]) if e.response
+
+                  raise
+                end
+              end
+            end
+
+            private
+
+            def span_creation_attributes(http_method:, url:, config:)
+              attrs = {
+                'http.method' => http_method,
+                'http.url' => OpenTelemetry::Common::Utilities.cleanse_url(url.to_s),
+                'faraday.adapter.name' => app.class.name
+              }
+              attrs['net.peer.name'] = url.host if url.host
+              attrs['peer.service'] = config[:peer_service] if config[:peer_service]
+
+              attrs.merge!(
+                OpenTelemetry::Common::HTTP::ClientContext.attributes
+              )
+            end
+
+            # Versions prior to 1.0 do not define an accessor for app
+            attr_reader :app if Gem::Version.new(Faraday::VERSION) < Gem::Version.new('1.0.0')
+
+            def tracer
+              Faraday::Instrumentation.instance.tracer
+            end
+
+            def trace_response(span, status)
+              span.set_attribute('http.status_code', status)
+              span.status = OpenTelemetry::Trace::Status.error unless HTTP_STATUS_SUCCESS_RANGE.cover?(status.to_i)
+            end
+          end
+        end
+      end
+    end
+  end
+end