opentelemetry-instrumentation-action_pack 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01fdccf711bd55c9f8e6df0d15bc871698058ba9500523696dbb22d2f3a28a4a
-  data.tar.gz: 55ecb33d2d56eec21b2cedee82df3189cb1c056a44464c34a2feadba6c327c76
+  metadata.gz: 5af8d8cb9038f564234140ffaa6d87f1b07ecb7021e4fe579ec5efc938b2898e
+  data.tar.gz: '091d78c0c499b98b31a31ea31aa6f0990f8cabe53dab62dd532036985def42ef'
 SHA512:
-  metadata.gz: d403b045b944b7062988e5e4a3a2e0a6c17d4a1e50409e1a920d36c27bcb19cd95b9de3aa8422dbcaa5b05443919165611478283ee2cc2477d0faf5a69d5f151
-  data.tar.gz: 2bc7459a91c2331288aebb7076c0f3e834aa966d7e8f751b79c14efcbc23eb5386147a4ce1acb65de750b6587f030a2cc4960f68e3296193773e92f0b13a4bd1
+  metadata.gz: 1e7782f0b1b04ab4a019677bd81a68c01954af5ece9a7f3b0073a764490241fed82b8173cc435fcbbcd7ec46786e1237a7b5e4406982de61674ad8285aafe60c
+  data.tar.gz: 97404fce81bd10262a19e129f6397aeaabe39ae54850a0f3d085952e6264e1392617727bab6a1fd22837338d48b2e603444a2392499168a0872abd0b62a71f06

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History: opentelemetry-instrumentation-action_pack
 
+### v0.10.0 / 2024-11-19
+
+* ADDED: Use Semconv Naming For ActionPack
+
+### v0.9.0 / 2024-01-09
+
+* BREAKING CHANGE: Use ActiveSupport instead of patches #703 
+
 ### v0.8.0 / 2023-11-22
 
 * BREAKING CHANGE: Drop Rails 6.0 EOL

data/README.md

@@ -6,7 +6,7 @@ The Action Pack instrumentation is a community-maintained instrumentation for th
 
 Install the gem using:
 
-```
+```console
 gem install opentelemetry-instrumentation-action_pack
 ```
 
@@ -30,6 +30,43 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
+## Active Support Instrumentation
+
+Earlier versions of this instrumentation relied on patching custom `dispatch` hooks from Rails's [Action Controller](https://github.com/rails/rails/blob/main/actionpack/lib/action_controller/metal.rb#L224) to extract request information.
+
+This instrumentation now relies on `ActiveSupport::Notifications` and registers a custom Subscriber that listens to relevant events to modify the Rack span.
+
+See the table below for details of what [Rails Framework Hook Events](https://guides.rubyonrails.org/active_support_instrumentation.html#action-controller) are recorded by this instrumentation:
+
+| Event Name | Subscribe? | Creates Span? |  Notes |
+| - | - | - | - |
+| `process_action.action_controller` | :white_check_mark: | :x: | It modifies the existing Rack span |
+
+## Semantic Conventions
+
+This instrumentation generally uses [HTTP server semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) to update the existing Rack span.
+
+For Rails 7.1+, the span name is updated to match the HTTP method and route that was matched for the request using [`ActionDispatch::Request#route_uri_pattern`](https://api.rubyonrails.org/classes/ActionDispatch/Request.html#method-i-route_uri_pattern), e.g.: `GET /users/:id`
+
+For older versions of Rails the span name is updated to match the HTTP method, controller, and action name that was the target of the request, e.g.: `GET /example/index`
+
+> ![NOTE]: Users may override the `span_naming` option to default to Legacy Span Naming Behavior that uses the controller's class name and action in Ruby documentation syntax, e.g. `ExampleController#index`.
+
+This instrumentation does not emit any custom attributes.
+
+| Attribute Name | Type | Notes |
+| - | - | - |
+| `code.namespace` | String | `ActionController` class name |
+| `code.function` | String | `ActionController` action name e.g. `index`, `show`, `edit`, etc... |
+| `http.route` | String | (Rails 7.1+) the route that was matched for the request |
+| `http.target` | String | The `request.filtered_path` |
+
+### Error Handling for Action Controller
+
+If an error is triggered by Action Controller (such as a 500 internal server error), Action Pack will typically employ the default `ActionDispatch::PublicExceptions.new(Rails.public_path)` as the `exceptions_app`, as detailed in the [documentation](https://guides.rubyonrails.org/configuring.html#config-exceptions-app).
+
+The error object will be retained within `payload[:exception_object]`. Additionally, its storage in `request.env['action_dispatch.exception']` is contingent upon the configuration of `action_dispatch.show_exceptions` in Rails.
+
 ## 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/action_pack/example/trace_demonstration.ru)
@@ -38,7 +75,7 @@ Example usage can be seen in the `./example/trace_demonstration.rb` file [here](
 
 The `opentelemetry-instrumentation-action_pack` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -49,4 +86,6 @@ The `opentelemetry-instrumentation-action_pack` gem is distributed under the Apa
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [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
+[rails-home]: https://rubyonrails.org/

data/lib/opentelemetry/instrumentation/action_pack/handlers/action_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module ActionPack
+      module Handlers
+        # Action Controller handler to handle the notification from Active Support
+        class ActionController
+          # @param config [Hash] of instrumentation options
+          def initialize(config)
+            @config = config
+            @span_naming = config.fetch(:span_naming)
+          end
+
+          # Invoked by ActiveSupport::Notifications at the start of the instrumentation block
+          #
+          # @param _name [String] of the event (unused)
+          # @param _id [String] of the event (unused)
+          # @param payload [Hash] the payload passed as a method argument
+          # @return [Hash] the payload passed as a method argument
+          def start(_name, _id, payload)
+            span_name, attributes = to_span_name_and_attributes(payload)
+
+            span = OpenTelemetry::Instrumentation::Rack.current_span
+            span.name = span_name
+            span.add_attributes(attributes)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(exception: e)
+          end
+
+          # Invoked by ActiveSupport::Notifications at the end of the instrumentation block
+          #
+          # @param _name [String] of the event (unused)
+          # @param _id [String] of the event (unused)
+          # @param payload [Hash] the payload passed as a method argument
+          # @return [Hash] the payload passed as a method argument
+          def finish(_name, _id, payload)
+            span = OpenTelemetry::Instrumentation::Rack.current_span
+            span.record_exception(payload[:exception_object]) if payload[:exception_object]
+          rescue StandardError => e
+            OpenTelemetry.handle_error(exception: e)
+          end
+
+          private
+
+          # Extracts the span name and attributes from the payload
+          #
+          # @param payload [Hash] the payload passed from ActiveSupport::Notifications
+          # @return [Array<String, Hash>] the span name and attributes
+          def to_span_name_and_attributes(payload)
+            request = payload[:request]
+            http_route = request.route_uri_pattern if request.respond_to?(:route_uri_pattern)
+
+            attributes = {
+              OpenTelemetry::SemanticConventions::Trace::CODE_NAMESPACE => String(payload[:controller]),
+              OpenTelemetry::SemanticConventions::Trace::CODE_FUNCTION => String(payload[:action])
+            }
+            attributes[OpenTelemetry::SemanticConventions::Trace::HTTP_ROUTE] = http_route if http_route
+            attributes[OpenTelemetry::SemanticConventions::Trace::HTTP_TARGET] = request.filtered_path if request.filtered_path != request.fullpath
+
+            if @span_naming == :semconv
+              return ["#{request.method} #{http_route.gsub('(.:format)', '')}", attributes] if http_route
+
+              return ["#{request.method} /#{payload.dig(:params, :controller)}/#{payload.dig(:params, :action)}", attributes]
+            end
+
+            ["#{payload[:controller]}##{payload[:action]}", attributes]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/action_pack/handlers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative 'handlers/action_controller'
+
+module OpenTelemetry
+  module Instrumentation
+    module ActionPack
+      # Module that contains custom event handlers, which are used to generate spans per event
+      module Handlers
+        module_function
+
+        def subscribe
+          return unless Array(@subscriptions).empty?
+
+          config = ActionPack::Instrumentation.instance.config
+          handlers_by_pattern = {
+            'process_action.action_controller' => Handlers::ActionController.new(config)
+          }
+
+          @subscriptions = handlers_by_pattern.map do |key, handler|
+            ::ActiveSupport::Notifications.subscribe(key, handler)
+          end
+        end
+
+        # Removes Event Handler Subscriptions for Action Controller notifications
+        # @note this method is not thread-safe and should not be used in a multi-threaded context
+        def unsubscribe
+          @subscriptions&.each { |subscriber| ::ActiveSupport::Notifications.unsubscribe(subscriber) }
+          @subscriptions = nil
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/instrumentation/action_pack/instrumentation.rb

@@ -7,7 +7,31 @@
 module OpenTelemetry
   module Instrumentation
     module ActionPack
-      # The Instrumentation class contains logic to detect and install the ActionPack instrumentation
+      # The {OpenTelemetry::Instrumentation::ActionPack::Instrumentation} class contains logic to detect and install the ActionPack instrumentation
+      #
+      # Installation and configuration of this instrumentation is done within the
+      # {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK#configure-instance_method OpenTelemetry::SDK#configure}
+      # block, calling {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry%2FSDK%2FConfigurator:use use()}
+      # or {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry%2FSDK%2FConfigurator:use_all use_all()}.
+      #
+      # ## Configuration keys and options
+      #
+      # ### `:span_naming`
+      #
+      # Specifies how the span names are set. Can be one of:
+      #
+      # - `:semconv` **(default)** - The span name will use HTTP semantic conventions '{method http.route}', for example `GET /users/:id`
+      # - `:class` - The span name will appear as '<ActionController class name>#<action>',
+      #   for example `UsersController#show`.
+      #
+      # @example An explicit default configuration
+      #   OpenTelemetry::SDK.configure do |c|
+      #     c.use_all({
+      #       'OpenTelemetry::Instrumentation::ActionPack' => {
+      #         span_naming: :class
+      #       },
+      #     })
+      #   end
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         MINIMUM_VERSION = Gem::Version.new('6.1.0')
 
@@ -17,6 +41,8 @@ module OpenTelemetry
           patch
         end
 
+        option :span_naming, default: :semconv, validate: %i[semconv class]
+
         present do
           defined?(::ActionController)
         end
@@ -32,11 +58,11 @@ module OpenTelemetry
         end
 
         def patch
-          ::ActionController::Metal.prepend(Patches::ActionController::Metal)
+          Handlers.subscribe
         end
 
         def require_dependencies
-          require_relative 'patches/action_controller/metal'
+          require_relative 'handlers'
         end
 
         def require_railtie

data/lib/opentelemetry/instrumentation/action_pack/version.rb

@@ -7,7 +7,7 @@
 module OpenTelemetry
   module Instrumentation
     module ActionPack
-      VERSION = '0.8.0'
+      VERSION = '0.10.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-instrumentation-action_pack
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-22 00:00:00.000000000 Z
+date: 2024-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -123,47 +123,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.3'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: 1.68.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: 1.68.0
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.56.1
+        version: 1.22.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.56.1
+        version: 1.22.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -184,14 +184,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.19'
+        version: 3.24.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.19'
+        version: 3.24.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -220,18 +220,19 @@ files:
 - lib/opentelemetry-instrumentation-action_pack.rb
 - lib/opentelemetry/instrumentation.rb
 - lib/opentelemetry/instrumentation/action_pack.rb
+- lib/opentelemetry/instrumentation/action_pack/handlers.rb
+- lib/opentelemetry/instrumentation/action_pack/handlers/action_controller.rb
 - lib/opentelemetry/instrumentation/action_pack/instrumentation.rb
-- lib/opentelemetry/instrumentation/action_pack/patches/action_controller/metal.rb
 - lib/opentelemetry/instrumentation/action_pack/railtie.rb
 - lib/opentelemetry/instrumentation/action_pack/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby-contrib
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-action_pack/0.8.0/file/CHANGELOG.md
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-action_pack/0.10.0/file/CHANGELOG.md
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/action_pack
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-action_pack/0.8.0
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-instrumentation-action_pack/0.10.0
 post_install_message: 
 rdoc_options: []
 require_paths:

data/lib/opentelemetry/instrumentation/action_pack/patches/action_controller/metal.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright The OpenTelemetry Authors
-#
-# SPDX-License-Identifier: Apache-2.0
-
-module OpenTelemetry
-  module Instrumentation
-    module ActionPack
-      module Patches
-        module ActionController
-          # Module to prepend to ActionController::Metal for instrumentation
-          module Metal
-            def dispatch(name, request, response)
-              rack_span = OpenTelemetry::Instrumentation::Rack.current_span
-              if rack_span.recording?
-                rack_span.name = "#{self.class.name}##{name}" unless request.env['action_dispatch.exception']
-
-                attributes_to_append = {
-                  OpenTelemetry::SemanticConventions::Trace::CODE_NAMESPACE => self.class.name,
-                  OpenTelemetry::SemanticConventions::Trace::CODE_FUNCTION => String(name)
-                }
-                attributes_to_append[OpenTelemetry::SemanticConventions::Trace::HTTP_TARGET] = request.filtered_path if request.filtered_path != request.fullpath
-                rack_span.add_attributes(attributes_to_append)
-              end
-
-              super(name, request, response)
-            end
-
-            private
-
-            def instrumentation_config
-              ActionPack::Instrumentation.instance.config
-            end
-          end
-        end
-      end
-    end
-  end
-end