Ethon instrumentation

CHANGELOG.md

@@ -2,7 +2,11 @@
 
 ## dev
 
-Version <dev> gleans Docker container IDs from cgroups v2-based containers, records additional synthetics attributes, fixes an issue with Rails 7.1 that could cause duplicate log records to be sent to New Relic, and fixes a deprecation warning for the Sidekiq error handler.
+Version <dev> adds instrumentation for Ethon, gleans Docker container IDs from cgroups v2-based containers, records additional synthetics attributes, fixes an issue with Rails 7.1 that could cause duplicate log records to be sent to New Relic, and fixes a deprecation warning for the Sidekiq error handler.
+
+- **Feature: Add instrumentation for Ethon**
+
+  Instrumentation has been added for the [Ethon](https://github.com/typhoeus/ethon) HTTP client gem. The agent will now record external request segments for invocations of `Ethon::Easy#perform` and `Ethon::Multi#perform`. NOTE: The [Typhoeus](https://github.com/typhoeus/typhoeus) gem is maintained by the same team that maintains Ethon and depends on Ethon for its functionality. The existing Typhoeus instrumentation provided by the agent will now cascade with the new Ethon instrumentation and Typhoeus users will now notice additional segments for the Ethon activity that was previously unreported. Users who use Ethon without Typhoeus will see only Ethon segments. [PR#2260](https://github.com/newrelic/newrelic-ruby-agent/pull/2260)
 
 - **Feature: Prevent the agent from starting in rails commands in Rails 7**
 

lib/new_relic/agent/configuration/default_source.rb

@@ -1429,6 +1429,14 @@ def self.enforce_fallback(allowed_values: nil, fallback: nil)
           :allowed_from_server => false,
           :description => 'Controls auto-instrumentation of the elasticsearch library at start-up. May be one of: `auto`, `prepend`, `chain`, `disabled`.'
         },
+        :'instrumentation.ethon' => {
+          :default => 'auto',
+          :public => true,
+          :type => String,
+          :dynamic_name => true,
+          :allowed_from_server => false,
+          :description => 'Controls auto-instrumentation of ethon at start up. May be one of [auto|prepend|chain|disabled]'
+        },
         :'instrumentation.excon' => {
           :default => 'enabled',
           :documentation_default => 'enabled',

lib/new_relic/agent/http_clients/ethon_wrappers.rb

@@ -0,0 +1,111 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'abstract'
+
+module NewRelic
+  module Agent
+    module HTTPClients
+      class EthonHTTPResponse < AbstractResponse
+        def initialize(easy)
+          @easy = easy
+        end
+
+        def status_code
+          @easy.response_code
+        end
+
+        def [](key)
+          headers[format_key(key)]
+        end
+
+        def headers
+          # Ethon::Easy#response_headers will return '' if headers are unset
+          @easy.response_headers.scan(/\n([^:]+?): ([^:\n]+?)\r/).each_with_object({}) do |pair, hash|
+            hash[format_key(pair[0])] = pair[1]
+          end
+        end
+        alias to_hash headers
+
+        private
+
+        def format_key(key)
+          key.tr('-', '_').downcase
+        end
+      end
+
+      class EthonHTTPRequest < AbstractRequest
+        attr_reader :uri
+
+        DEFAULT_ACTION = 'GET'
+        DEFAULT_HOST = 'UNKNOWN_HOST'
+        ETHON = 'Ethon'
+        LHOST = 'host'.freeze
+        UHOST = 'Host'.freeze
+
+        def initialize(easy)
+          @easy = easy
+          @uri = uri_from_easy
+        end
+
+        def type
+          ETHON
+        end
+
+        def host_from_header
+          self[LHOST] || self[UHOST]
+        end
+
+        def uri_from_easy
+          # anticipate `Ethon::Easy#url` being `example.com` without a protocol
+          # defined and use an 'http' protocol prefix for `URI.parse` to work
+          # with the URL as desired
+          url_str = @easy.url.match?(':') ? @easy.url : "http://#{@easy.url}"
+          begin
+            URI.parse(url_str)
+          rescue URI::InvalidURIError => e
+            NewRelic::Agent.logger.debug("Failed to parse URI '#{url_str}': #{e.class} - #{e.message}")
+            URI.parse(NewRelic::EMPTY_STR)
+          end
+        end
+
+        def host
+          host_from_header || uri.host&.downcase || DEFAULT_HOST
+        end
+
+        def method
+          return DEFAULT_ACTION unless @easy.instance_variable_defined?(action_instance_var)
+
+          @easy.instance_variable_get(action_instance_var)
+        end
+
+        def action_instance_var
+          NewRelic::Agent::Instrumentation::Ethon::Easy::ACTION_INSTANCE_VAR
+        end
+
+        def []=(key, value)
+          headers[key] = value
+          @easy.headers = headers
+        end
+
+        def headers
+          @headers ||= if @easy.instance_variable_defined?(headers_instance_var)
+            @easy.instance_variable_get(headers_instance_var)
+          else
+            {}
+          end
+        end
+
+        def headers_instance_var
+          NewRelic::Agent::Instrumentation::Ethon::Easy::HEADERS_INSTANCE_VAR
+        end
+
+        def [](key)
+          headers[key]
+        end
+      end
+    end
+  end
+end

lib/new_relic/agent/instrumentation/ethon.rb

@@ -0,0 +1,30 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require_relative 'ethon/instrumentation'
+require_relative 'ethon/chain'
+require_relative 'ethon/prepend'
+
+DependencyDetection.defer do
+  named :ethon
+
+  depends_on do
+    defined?(Ethon) && Gem::Version.new(Ethon::VERSION) >= Gem::Version.new('0.12.0')
+  end
+
+  executes do
+    NewRelic::Agent.logger.info('Installing ethon instrumentation')
+  end
+
+  executes do
+    if use_prepend?
+      # NOTE: to prevent a string like 'Ethon::Easy' from being converted into
+      #       'Ethon/Easy', a 3rd argument is supplied to `prepend_instrument`
+      prepend_instrument Ethon::Easy, NewRelic::Agent::Instrumentation::Ethon::Easy::Prepend, Ethon::Easy.name
+      prepend_instrument Ethon::Multi, NewRelic::Agent::Instrumentation::Ethon::Multi::Prepend, Ethon::Multi.name
+    else
+      chain_instrument NewRelic::Agent::Instrumentation::Ethon::Chain
+    end
+  end
+end

lib/new_relic/agent/instrumentation/ethon/chain.rb

@@ -0,0 +1,39 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module NewRelic::Agent::Instrumentation
+  module Ethon
+    module Chain
+      def self.instrument!
+        ::Ethon::Easy.class_eval do
+          include NewRelic::Agent::Instrumentation::Ethon::Easy
+
+          alias_method(:fabricate_without_tracing, :fabricate)
+          def fabricate(url, action_name, options)
+            fabricate_with_tracing(url, action_name, options) { fabricate_without_tracing(url, action_name, options) }
+          end
+
+          alias_method(:headers_equals_without_tracing, :headers=)
+          def headers=(headers)
+            headers_equals_with_tracing(headers) { headers_equals_without_tracing(headers) }
+          end
+
+          alias_method(:perform_without_tracing, :perform)
+          def perform(*args)
+            perform_with_tracing(*args) { perform_without_tracing(*args) }
+          end
+        end
+
+        ::Ethon::Multi.class_eval do
+          include NewRelic::Agent::Instrumentation::Ethon::Multi
+
+          alias_method(:perform_without_tracing, :perform)
+          def perform(*args)
+            perform_with_tracing(*args) { perform_without_tracing(*args) }
+          end
+        end
+      end
+    end
+  end
+end

lib/new_relic/agent/instrumentation/ethon/instrumentation.rb

@@ -0,0 +1,105 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+require 'new_relic/agent/http_clients/ethon_wrappers'
+
+module NewRelic::Agent::Instrumentation
+  module Ethon
+    module NRShared
+      INSTRUMENTATION_NAME = 'Ethon'
+      NOTICEABLE_ERROR_CLASS = 'Ethon::Errors::EthonError'
+
+      def prep_easy(easy, parent = nil)
+        wrapped_request = NewRelic::Agent::HTTPClients::EthonHTTPRequest.new(easy)
+        segment = NewRelic::Agent::Tracer.start_external_request_segment(
+          library: wrapped_request.type,
+          uri: wrapped_request.uri,
+          procedure: wrapped_request.method,
+          parent: parent
+        )
+        segment.add_request_headers(wrapped_request)
+
+        callback = proc do
+          wrapped_response = NewRelic::Agent::HTTPClients::EthonHTTPResponse.new(easy)
+          segment.process_response_headers(wrapped_response)
+
+          if easy.return_code != :ok
+            e = NewRelic::Agent::NoticeableError.new(NOTICEABLE_ERROR_CLASS,
+              "return_code: >>#{easy.return_code}<<, response_code: >>#{easy.response_code}<<")
+            segment.notice_error(e)
+          end
+
+          ::NewRelic::Agent::Transaction::Segment.finish(segment)
+        end
+
+        easy.on_complete { callback.call }
+
+        segment
+      end
+
+      def wrap_with_tracing(segment, &block)
+        NewRelic::Agent.record_instrumentation_invocation(INSTRUMENTATION_NAME)
+
+        NewRelic::Agent::Tracer.capture_segment_error(segment) do
+          yield
+        end
+      ensure
+        NewRelic::Agent::Transaction::Segment.finish(segment)
+      end
+    end
+
+    module Easy
+      include NRShared
+
+      ACTION_INSTANCE_VAR = :@nr_action
+      HEADERS_INSTANCE_VAR = :@nr_headers
+
+      # `Ethon::Easy` doesn't expose the "action name" ('GET', 'POST', etc.)
+      # and Ethon's fabrication of HTTP classes uses
+      # `Ethon::Easy::Http::Custom` for non-standard actions. To be able to
+      # know the action name at `#perform` time, we set a new instance variable
+      # on the `Ethon::Easy` instance with the base name of the fabricated
+      # class, respecting the 'Custom' name where appropriate.
+      def fabricate_with_tracing(_url, action_name, _options)
+        fabbed = yield
+        instance_variable_set(ACTION_INSTANCE_VAR, NewRelic::Agent.base_name(fabbed.class.name).upcase)
+        fabbed
+      end
+
+      # `Ethon::Easy` uses `Ethon::Easy::Header` to set request headers on
+      # libcurl with `#headers=`. After they are set, they aren't easy to get
+      # at again except via FFI so set a new instance variable on the
+      # `Ethon::Easy` instance to store them in Ruby hash format.
+      def headers_equals_with_tracing(headers)
+        instance_variable_set(HEADERS_INSTANCE_VAR, headers)
+        yield
+      end
+
+      def perform_with_tracing(*args)
+        return unless NewRelic::Agent::Tracer.state.is_execution_traced?
+
+        segment = prep_easy(self)
+        wrap_with_tracing(segment) { yield }
+      end
+    end
+
+    module Multi
+      include NRShared
+
+      MULTI_SEGMENT_NAME = 'External/Multiple/Ethon::Multi/perform'
+
+      def perform_with_tracing(*args)
+        return unless NewRelic::Agent::Tracer.state.is_execution_traced?
+
+        segment = NewRelic::Agent::Tracer.start_segment(name: MULTI_SEGMENT_NAME)
+
+        wrap_with_tracing(segment) do
+          easy_handles.each { |easy| prep_easy(easy, segment) }
+
+          yield
+        end
+      end
+    end
+  end
+end

lib/new_relic/agent/instrumentation/ethon/prepend.rb

@@ -0,0 +1,35 @@
+# This file is distributed under New Relic's license terms.
+# See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details.
+# frozen_string_literal: true
+
+module NewRelic::Agent::Instrumentation
+  module Ethon
+    module Easy
+      module Prepend
+        include NewRelic::Agent::Instrumentation::Ethon::Easy
+
+        def fabricate(url, action_name, options)
+          fabricate_with_tracing(url, action_name, options) { super }
+        end
+
+        def headers=(headers)
+          headers_equals_with_tracing(headers) { super }
+        end
+
+        def perform(*args)
+          perform_with_tracing(*args) { super }
+        end
+      end
+    end
+
+    module Multi
+      module Prepend
+        include NewRelic::Agent::Instrumentation::Ethon::Multi
+
+        def perform(*args)
+          perform_with_tracing(*args) { super }
+        end
+      end
+    end
+  end
+end

lib/new_relic/agent/tracer.rb

@@ -357,9 +357,7 @@ def capture_segment_error(segment)
           yield
         rescue => exception
           # needs else branch coverage
-          if segment && segment.is_a?(Transaction::AbstractSegment) # rubocop:disable Style/SafeNavigation
-            segment.notice_error(exception)
-          end
+          segment.notice_error(exception) if segment&.is_a?(Transaction::AbstractSegment)
           raise
         end