opentelemetry-instrumentation-rack 0.26.0 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac289c86c4ea8754cb2d6fd9cd54939a18749879c548a7a0b268d03f0c1655fb
-  data.tar.gz: c7f576b24aa2d5ba3481e42c1b85761475d27b141d8302c9739fbca326b128cc
+  metadata.gz: e564fc1183315722b2f2a964482cc019b7f9667c9186dd3386582ab9f560d578
+  data.tar.gz: d8b4659e25076da7b89900bae8955b0ca07222a839f7f5ed3add5079d928635d
 SHA512:
-  metadata.gz: c4d760431593691b8821997ac0f6fdec37d225485a847d37b945e2651254155a5046110c5f856ca30b172bbf2a6894cdf5e9eb4d0f3cd356eb347b759d6f8dac
-  data.tar.gz: 1f69336f2340ecc191b490552f204f35a124643092c68ff596fb49674440c2662c1a3919ee34fb3c51cab1cafbc9e9487586d5d7d203e0f3116ca4634e638d84
+  metadata.gz: 331443dd4ac9af20a3df6e9fae7ad0d496947938b0b3369b3e2ca7550d19401f07ccc3c44e2fca73a0ca55c08dda9f903ccdb592af8918016e46be8f3a814a73
+  data.tar.gz: 26d2eab4e04f1edfe08165d9f44558a2f677030bfacc3b6f6c03f97107687c4d2693f65f55a2f1f2e96f847d9b38dcba5eccdcfe8bb4d2bb076ff9cd2a265b61

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History: opentelemetry-instrumentation-rack
 
+### v0.27.1 / 2025-09-16
+
+* DOCS: Typo in Rack::Instrumentation usage example of middleware_args
+
+### v0.27.0 / 2025-08-19
+
+* ADDED: Add `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable compatibility [#1594](https://github.com/open-telemetry/opentelemetry-ruby-contrib/pull/1594)
+
 ### v0.26.0 / 2025-01-16
 
 * BREAKING CHANGE: Set minimum supported version to Ruby 3.1
@@ -59,21 +67,21 @@
 
 ### v0.23.1 / 2023-06-05
 
-* FIXED: Base config options 
+* FIXED: Base config options
 
 ### v0.23.0 / 2023-04-17
 
-* BREAKING CHANGE: Remove retain_middleware_names Rack Option 
-* BREAKING CHANGE: Drop support for EoL Ruby 2.7 
+* BREAKING CHANGE: Remove retain_middleware_names Rack Option
+* BREAKING CHANGE: Drop support for EoL Ruby 2.7
 
-* ADDED: Remove retain_middleware_names Rack Option 
-* ADDED: Drop support for EoL Ruby 2.7 
-* ADDED: Use Rack::Events for instrumentation 
+* ADDED: Remove retain_middleware_names Rack Option
+* ADDED: Drop support for EoL Ruby 2.7
+* ADDED: Use Rack::Events for instrumentation
 
 ### v0.22.1 / 2023-01-14
 
-* DOCS: Fix gem homepage 
-* DOCS: More gem documentation fixes 
+* DOCS: Fix gem homepage
+* DOCS: More gem documentation fixes
 
 ### v0.22.0 / 2022-11-16
 
@@ -86,17 +94,17 @@
 ### v0.21.0 / 2022-06-09
 
 * Upgrading Base dependency version
-* FIXED: Broken test file requirements 
+* FIXED: Broken test file requirements
 
 ### v0.20.2 / 2022-05-02
 
-* FIXED: Update server instrumentation to not reflect 400 status as error 
+* FIXED: Update server instrumentation to not reflect 400 status as error
 
 ### v0.20.1 / 2021-12-01
 
-* FIXED: [Instrumentation Rack] Log content type http header 
-* FIXED: Use monotonic clock where possible 
-* FIXED: Rack to stop using api env getter 
+* FIXED: [Instrumentation Rack] Log content type http header
+* FIXED: Use monotonic clock where possible
+* FIXED: Rack to stop using api env getter
 
 ### v0.20.0 / 2021-10-06
 
@@ -114,18 +122,18 @@ forwards the uri path.  More details on this is available in the readme.
 
 ### v0.19.2 / 2021-08-18
 
-* FIXED: Rack middleware assuming script_name presence 
+* FIXED: Rack middleware assuming script_name presence
 
 ### v0.19.1 / 2021-08-12
 
-* DOCS: Update docs to rely more on environment variable configuration 
+* DOCS: Update docs to rely more on environment variable configuration
 
 ### v0.19.0 / 2021-06-23
 
-* BREAKING CHANGE: Total order constraint on span.status= 
+* BREAKING CHANGE: Total order constraint on span.status=
 
-* ADDED: Add Tracer.non_recording_span to API 
-* FIXED: Total order constraint on span.status= 
+* ADDED: Add Tracer.non_recording_span to API
+* FIXED: Total order constraint on span.status=
 
 ### v0.18.0 / 2021-05-21
 

data/README.md

@@ -81,7 +81,7 @@ end
 
 ## Examples
 
-Example usage can be seen in the `./example/trace_demonstration.rb` file [here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/instrumentation/rack/example/trace_demonstration.rb)
+Example usage can be seen in the [`./example/trace_demonstration.rb` file](https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/instrumentation/rack/example/trace_demonstration.rb)
 
 ## How can I get involved?
 
@@ -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/).

data/lib/opentelemetry/instrumentation/rack/instrumentation.rb

@@ -13,7 +13,8 @@ module OpenTelemetry
       # 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,64 @@ module OpenTelemetry
         #
         # @example Default usage
         #   Rack::Builder.new do
-        #     use *OpenTelemetry::Instrumentation::Rack::Instrumenation.instance.middleware_args
+        #     use *OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args
         #     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]]
+          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
+
+        alias middleware_args_old middleware_args
+
+        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)

data/lib/opentelemetry/instrumentation/rack/middlewares/dup/event_handler.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative '../../util'
+require 'opentelemetry/trace/status'
+
+module OpenTelemetry
+  module Instrumentation
+    module Rack
+      module Middlewares
+        module Dup
+          # OTel Rack Event Handler
+          #
+          # This seeds the root context for this service with the server span as the `current_span`
+          # allowing for callers later in the stack to reference it using {OpenTelemetry::Trace.current_span}
+          #
+          # It also registers the server span in a context dedicated to this instrumentation that users may look up
+          # using {OpenTelemetry::Instrumentation::Rack.current_span}, which makes it possible for users to mutate the span,
+          # e.g. add events or update the span name like in the {ActionPack} instrumentation.
+          #
+          # @example Rack App Using BodyProxy
+          #   GLOBAL_LOGGER = Logger.new($stderr)
+          #   APP_TRACER = OpenTelemetry.tracer_provider.tracer('my-app', '1.0.0')
+          #
+          #   Rack::Builder.new do
+          #     use Rack::Events, [OpenTelemetry::Instrumentation::Rack::Middlewares::EventHandler.new]
+          #     run lambda { |_arg|
+          #       APP_TRACER.in_span('hello-world') do |_span|
+          #         body = Rack::BodyProxy.new(['hello world!']) do
+          #           rack_span = OpenTelemetry::Instrumentation::Rack.current_span
+          #           GLOBAL_LOGGER.info("otel.trace_id=#{rack_span.context.hex_trace_id} otel.span_id=#{rack_span.context.hex_span_id}")
+          #         end
+          #         [200, { 'Content-Type' => 'text/plain' }, body]
+          #       end
+          #     }
+          #   end
+          #
+          # @see Rack::Events
+          # @see OpenTelemetry::Instrumentation::Rack.current_span
+          class EventHandler
+            include ::Rack::Events::Abstract
+
+            OTEL_TOKEN_AND_SPAN = 'otel.rack.token_and_span'
+            EMPTY_HASH = {}.freeze
+
+            # Creates a server span for this current request using the incoming parent context
+            # and registers them as the {current_span}
+            #
+            # @param [Rack::Request] The current HTTP request
+            # @param [Rack::Response] This is nil in practice
+            # @return [void]
+            def on_start(request, _)
+              parent_context = if untraced_request?(request.env)
+                                 extract_remote_context(request, OpenTelemetry::Common::Utilities.untraced)
+                               else
+                                 extract_remote_context(request)
+                               end
+
+              span = create_span(parent_context, request)
+              span_ctx = OpenTelemetry::Trace.context_with_span(span, parent_context: parent_context)
+              rack_ctx = OpenTelemetry::Instrumentation::Rack.context_with_span(span, parent_context: span_ctx)
+              request.env[OTEL_TOKEN_AND_SPAN] = [OpenTelemetry::Context.attach(rack_ctx), span]
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            end
+
+            # Optionally adds debugging response headers injected from {response_propagators}
+            #
+            # @param [Rack::Request] The current HTTP request
+            # @param [Rack::Response] This current HTTP response
+            # @return [void]
+            def on_commit(request, response)
+              span = OpenTelemetry::Instrumentation::Rack.current_span
+              return unless span.recording?
+
+              response_propagators&.each do |propagator|
+                propagator.inject(response.headers)
+              rescue StandardError => e
+                OpenTelemetry.handle_error(message: 'Unable to inject response propagation headers', exception: e)
+              end
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            end
+
+            # Records Unexpected Exceptions on the Rack span and set the Span Status to Error
+            #
+            # @note does nothing if the span is a non-recording span
+            # @param [Rack::Request] The current HTTP request
+            # @param [Rack::Response] The current HTTP response
+            # @param [Exception] An unxpected error raised by the application
+            def on_error(request, _, error)
+              span = OpenTelemetry::Instrumentation::Rack.current_span
+              return unless span.recording?
+
+              span.record_exception(error)
+              span.status = OpenTelemetry::Trace::Status.error(error.class.name)
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            end
+
+            # Finishes the span making it eligible to be exported and cleans up existing contexts
+            #
+            # @note does nothing if the span is a non-recording span
+            # @param [Rack::Request] The current HTTP request
+            # @param [Rack::Response] The current HTTP response
+            def on_finish(request, response)
+              span = OpenTelemetry::Instrumentation::Rack.current_span
+              return unless span.recording?
+
+              add_response_attributes(span, response) if response
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            ensure
+              detach_context(request)
+            end
+
+            private
+
+            def extract_request_headers(env)
+              return EMPTY_HASH if allowed_request_headers.empty?
+
+              allowed_request_headers.each_with_object({}) do |(key, value), result|
+                result[value] = env[key] if env.key?(key)
+              end
+            end
+
+            def extract_response_attributes(response)
+              attributes = {
+                'http.status_code' => response.status.to_i,
+                'http.response.status_code' => response.status.to_i
+              }
+              attributes.merge!(extract_response_headers(response.headers))
+              attributes
+            end
+
+            def extract_response_headers(headers)
+              return EMPTY_HASH if allowed_response_headers.empty?
+
+              allowed_response_headers.each_with_object({}) do |(key, value), result|
+                if headers.key?(key)
+                  result[value] = headers[key]
+                else
+                  # do case-insensitive match:
+                  headers.each do |k, v|
+                    if k.upcase == key
+                      result[value] = v
+                      break
+                    end
+                  end
+                end
+              end
+            end
+
+            def untraced_request?(env)
+              return true if untraced_endpoints.include?(env['PATH_INFO'])
+              return true if untraced_requests&.call(env)
+
+              false
+            end
+
+            # https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#name
+            #
+            # recommendation: span.name(s) should be low-cardinality (e.g.,
+            # strip off query param value, keep param name)
+            #
+            # see http://github.com/open-telemetry/opentelemetry-specification/pull/416/files
+            def create_request_span_name(request)
+              # NOTE: dd-trace-rb has implemented 'quantization' (which lowers url cardinality)
+              #       see Datadog::Quantization::HTTP.url
+
+              if (implementation = url_quantization)
+                request_uri_or_path_info = request.env['REQUEST_URI'] || request.path_info
+                implementation.call(request_uri_or_path_info, request.env)
+              else
+                request.request_method.to_s
+              end
+            end
+
+            def extract_remote_context(request, context = Context.current)
+              OpenTelemetry.propagation.extract(
+                request.env,
+                context: context,
+                getter: OpenTelemetry::Common::Propagation.rack_env_getter
+              )
+            end
+
+            def request_span_attributes(env)
+              attributes = {
+                'http.method' => env['REQUEST_METHOD'],
+                'http.host' => env['HTTP_HOST'] || 'unknown',
+                'server.address' => env['HTTP_HOST'] || 'unknown',
+                'http.scheme' => env['rack.url_scheme'],
+                'http.target' => env['QUERY_STRING'].empty? ? env['PATH_INFO'] : "#{env['PATH_INFO']}?#{env['QUERY_STRING']}",
+                'http.request.method' => env['REQUEST_METHOD'],
+                'url.scheme' => env['rack.url_scheme'],
+                'url.path' => env['PATH_INFO']
+              }
+
+              attributes['url.query'] = env['QUERY_STRING'] unless env['QUERY_STRING'].empty?
+              if env['HTTP_USER_AGENT']
+                attributes['http.user_agent'] = env['HTTP_USER_AGENT']
+                attributes['user_agent.original'] = env['HTTP_USER_AGENT']
+              end
+              attributes.merge!(extract_request_headers(env))
+              attributes
+            end
+
+            def detach_context(request)
+              return nil unless request.env[OTEL_TOKEN_AND_SPAN]
+
+              token, span = request.env[OTEL_TOKEN_AND_SPAN]
+              span.finish
+              OpenTelemetry::Context.detach(token)
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            end
+
+            def add_response_attributes(span, response)
+              span.status = OpenTelemetry::Trace::Status.error if response.server_error?
+              attributes = extract_response_attributes(response)
+              span.add_attributes(attributes)
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e)
+            end
+
+            def record_frontend_span?
+              config[:record_frontend_span] == true
+            end
+
+            def untraced_endpoints
+              config[:untraced_endpoints]
+            end
+
+            def untraced_requests
+              config[:untraced_requests]
+            end
+
+            def url_quantization
+              config[:url_quantization]
+            end
+
+            def response_propagators
+              config[:response_propagators]
+            end
+
+            def allowed_request_headers
+              config[:allowed_rack_request_headers]
+            end
+
+            def allowed_response_headers
+              config[:allowed_rack_response_headers]
+            end
+
+            def tracer
+              OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.tracer
+            end
+
+            def config
+              OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.config
+            end
+
+            def create_span(parent_context, request)
+              span = tracer.start_span(
+                create_request_span_name(request),
+                with_parent: parent_context,
+                kind: :server,
+                attributes: request_span_attributes(request.env)
+              )
+              request_start_time = OpenTelemetry::Instrumentation::Rack::Util::QueueTime.get_request_start(request.env)
+              span.add_event('http.proxy.request.started', timestamp: request_start_time) unless request_start_time.nil?
+              span
+            end
+          end
+        end
+      end
+    end
+  end
+end