datadog 2.4.0 → 2.44.0

data/lib/datadog/{tracing → core}/transport/http/builder.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
-require_relative '../../../core/configuration/agent_settings_resolver'
-require_relative '../../../core/transport/http/adapters/registry'
-require_relative '../../../core/transport/http/api/map'
-require_relative 'api/instance'
-require_relative 'client'
+require_relative "../../configuration/agent_settings"
+require_relative "adapters/registry"
+require_relative "api/map"
 
 module Datadog
-  module Tracing
+  module Core
     module Transport
       module HTTP
         # Builds new instances of Transport::HTTP::Client
@@ -19,9 +17,10 @@ module Datadog
             :api_options,
             :default_adapter,
             :default_api,
-            :default_headers
+            :default_headers,
+            :logger
 
-          def initialize
+          def initialize(logger: Datadog.logger)
             # Global settings
             @default_adapter = nil
             @default_headers = {}
@@ -33,24 +32,26 @@ module Datadog
             # API settings
             @api_options = {}
 
+            @logger = logger
+
             yield(self) if block_given?
           end
 
           def adapter(config, *args, **kwargs)
             @default_adapter = case config
-                               when Core::Configuration::AgentSettingsResolver::AgentSettings
-                                 registry_klass = REGISTRY.get(config.adapter)
-                                 raise UnknownAdapterError, config.adapter if registry_klass.nil?
-
-                                 registry_klass.build(config)
-                               when Symbol
-                                 registry_klass = REGISTRY.get(config)
-                                 raise UnknownAdapterError, config if registry_klass.nil?
-
-                                 registry_klass.new(*args, **kwargs)
-                               else
-                                 config
-                               end
+            when Core::Configuration::AgentSettings
+              registry_klass = REGISTRY.get(config.adapter)
+              raise UnknownAdapterError, config.adapter if registry_klass.nil?
+
+              registry_klass.build(config)
+            when Symbol
+              registry_klass = REGISTRY.get(config)
+              raise UnknownAdapterError, config if registry_klass.nil?
+
+              registry_klass.new(*args, **kwargs)
+            else
+              config
+            end
           end
 
           def headers(values = {})
@@ -70,6 +71,12 @@ module Datadog
             @apis[key] = spec
 
             # Apply as default API, if specified to do so.
+            #
+            # This code also sets the first defined API to be the default API.
+            # In APIs without fallbacks (currently, everything other than
+            # tracing's Traces, though DI Input will also have fallbacks soon)
+            # there is only one declaration of `transport.api`, and that
+            # API is set as the default API in the transport by this line.
             @default_api = key if options.delete(:default) || @default_api.nil?
 
             # Save all other settings for initialization
@@ -82,17 +89,16 @@ module Datadog
             @default_api = key
           end
 
-          def to_transport
+          def to_transport(klass)
             raise NoDefaultApiError if @default_api.nil?
 
-            # DEV: Should not be specific to traces
-            Transport::Traces::Transport.new(to_api_instances, @default_api)
+            klass.new(to_api_instances, @default_api, logger: logger)
           end
 
           def to_api_instances
             raise NoApisError if @apis.empty?
 
-            @apis.inject(Datadog::Core::Transport::HTTP::API::Map.new) do |instances, (key, spec)|
+            @apis.inject(API::Map.new) do |instances, (key, spec)|
               instances.tap do
                 api_options = @api_options[key].dup
 
@@ -102,10 +108,10 @@ module Datadog
 
                 # Resolve fallback and merge headers
                 fallback = api_options.delete(:fallback)
-                api_options[:headers] = @default_headers.merge((api_options[:headers] || {}))
+                api_options[:headers] = @default_headers.merge(api_options[:headers] || {})
 
                 # Add API::Instance with all settings
-                instances[key] = api_instance_class.new(
+                instances[key] = API::Instance.new(
                   spec,
                   adapter,
                   api_options
@@ -117,42 +123,62 @@ module Datadog
             end
           end
 
-          def api_instance_class
-            API::Instance
-          end
-
           # Raised when the API key does not match known APIs.
           class UnknownApiError < StandardError
+            attr_reader :key
+
             def initialize(key)
-              super("Unknown transport API '#{key}'!")
+              super()
+
+              @key = key
+            end
+
+            def message
+              "Unknown transport API '#{key}'!"
             end
           end
 
           # Raised when the identifier cannot be matched to an adapter.
           class UnknownAdapterError < StandardError
+            attr_reader :type
+
             def initialize(type)
-              super("Unknown transport adapter '#{type}'!")
+              super()
+
+              @type = type
+            end
+
+            def message
+              "Unknown transport adapter '#{type}'!"
             end
           end
 
           # Raised when an adapter cannot be resolved for an API instance.
           class NoAdapterForApiError < StandardError
+            attr_reader :key
+
             def initialize(key)
-              super("No adapter resolved for transport API '#{key}'!")
+              super()
+
+              @key = key
+            end
+
+            def message
+              "No adapter resolved for transport API '#{key}'!"
             end
           end
 
           # Raised when built without defining APIs.
           class NoApisError < StandardError
             def message
-              'No APIs configured for transport!'
+              "No APIs configured for transport!"
             end
           end
 
           # Raised when client built without defining a default API.
           class NoDefaultApiError < StandardError
             def message
-              'No default API configured for transport!'
+              "No default API configured for transport!"
             end
           end
         end

data/lib/datadog/core/transport/http/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "env"
+require_relative "../response"
+
+module Datadog
+  module Core
+    module Transport
+      module HTTP
+        # Routes, encodes, and sends DI data to the trace agent via HTTP.
+        #
+        # @api private
+        class Client
+          attr_reader :instance, :logger
+
+          def initialize(instance, logger:)
+            @instance = instance
+            @logger = logger
+          end
+
+          def send_request(action, request)
+            # Build request into env
+            env = build_env(request)
+
+            # Get responses from API.
+            # All of our APIs send only one type of request each.
+            instance.endpoint.call(env) do |request_env|
+              instance.call(request_env)
+            end.tap do |response|
+              unless response.ok?
+                # This logging is on debug level.
+                # To report the failed operations on lower levels,
+                # throttling needs to be implemented because
+                # agent unavailability can produce a lot of spam that would
+                # be not desired by customers.
+                # Some transports do report failed operations on warn level
+                # with such throttling.
+                logger.debug { "send_request #{action.inspect} failed: #{response.inspect}" }
+              end
+              on_response(response)
+            end
+          rescue => exception
+            on_exception(exception)
+
+            Datadog::Core::Transport::InternalErrorResponse.new(exception)
+          end
+
+          def build_env(request)
+            Datadog::Core::Transport::HTTP::Env.new(request)
+          end
+
+          # Callback that is invoked if a request did not raise an exception
+          # (but did not necessarily complete successfully).
+          #
+          # Override in subclasses.
+          #
+          # Note that the client will return the original response -
+          # the return value of this method is ignored, and response should
+          # not be modified.
+          def on_response(response)
+          end
+
+          # Callback that is invoked if a request failed with an exception.
+          #
+          # Override in subclasses.
+          def on_exception(exception)
+            message = build_exception_message(exception)
+
+            logger.debug(message)
+          end
+
+          def build_exception_message(exception)
+            "Internal error during #{self.class.name} request. Cause: #{exception.class}: #{exception} " \
+              "Location: #{Array(exception.backtrace).first}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/transport/http/env.rb

@@ -32,6 +32,14 @@ module Datadog
             self[:path] = value
           end
 
+          def query
+            self[:query]
+          end
+
+          def query=(value)
+            self[:query] = value
+          end
+
           def body
             self[:body]
           end

data/lib/datadog/core/transport/http/response.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../../core/transport/response'
+require_relative "../../../core/transport/response"
 
 module Datadog
   module Core
@@ -53,6 +53,10 @@ module Datadog
           def code
             @http_response.respond_to?(:code) ? @http_response.code : nil
           end
+
+          def headers
+            @http_response.respond_to?(:headers) ? @http_response.headers : {}
+          end
         end
       end
     end

data/lib/datadog/core/transport/http.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "http/builder"
+require_relative "http/adapters/net"
+require_relative "http/adapters/unix_socket"
+require_relative "http/adapters/test"
+require_relative "../environment/container"
+require_relative "../environment/ext"
+
+module Datadog
+  module Core
+    module Transport
+      # HTTP transport
+      module HTTP
+        # Add adapters to registry
+        Builder::REGISTRY.set(
+          Core::Transport::HTTP::Adapters::Net,
+          Core::Configuration::Ext::Agent::HTTP::ADAPTER
+        )
+        Builder::REGISTRY.set(
+          Core::Transport::HTTP::Adapters::Test,
+          Core::Transport::Ext::Test::ADAPTER
+        )
+        Builder::REGISTRY.set(
+          Core::Transport::HTTP::Adapters::UnixSocket,
+          Core::Transport::Ext::UnixSocket::ADAPTER
+        )
+
+        module_function
+
+        # Helper function that delegates to Builder.new
+        # but is under HTTP namespace so that client code requires this file
+        # to get the adapters configured, and not the builder directly.
+        def build(
+          agent_settings:,
+          logger: Datadog.logger,
+          headers: nil,
+          &block
+        )
+          Builder.new(logger: logger) do |transport|
+            transport.adapter(agent_settings)
+            transport.headers(default_headers)
+
+            # The caller must define APIs before we set the default API.
+            yield transport
+
+            # Apply any settings given by options
+            transport.headers(headers) if headers
+          end
+        end
+
+        def default_headers
+          {
+            Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_TOP_LEVEL => "1",
+            Core::Transport::Ext::HTTP::HEADER_META_LANG =>
+              Datadog::Core::Environment::Ext::LANG,
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_VERSION =>
+              Datadog::Core::Environment::Ext::LANG_VERSION,
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER =>
+              Datadog::Core::Environment::Ext::LANG_INTERPRETER,
+            Core::Transport::Ext::HTTP::HEADER_META_LANG_INTERPRETER_VENDOR =>
+              Core::Environment::Ext::LANG_ENGINE,
+            Core::Transport::Ext::HTTP::HEADER_META_TRACER_VERSION =>
+              Datadog::Core::Environment::Ext::GEM_DATADOG_VERSION,
+          }.tap do |headers|
+            # Add application container info
+            headers.merge!(Core::Environment::Container.to_headers)
+
+            # TODO: inject configuration rather than reading from global here
+            unless Datadog.configuration.apm.tracing.enabled
+              # Sending this header to the agent will disable metrics computation (and billing) on the agent side
+              # by pretending it has already been done on the library side.
+              headers[Core::Transport::Ext::HTTP::HEADER_CLIENT_COMPUTED_STATS] = "yes"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/transport/parcel.rb

@@ -3,19 +3,71 @@
 module Datadog
   module Core
     module Transport
-      # Data transfer object for generic data
-      # @abstract
-      module Parcel
-        attr_reader \
-          :data
-
-        def initialize(data)
+      # Data transfer object for transporting already-encoded data.
+      #
+      # A Parcel is a container that holds pre-encoded data along with metadata
+      # about its encoding. The key design principle is that encoding happens
+      # BEFORE the Parcel is created, not inside it.
+      #
+      # @example Creating a Parcel with JSON data
+      #   encoder = Core::Encoding::JSONEncoder
+      #   parcel = Parcel.new(
+      #     encoder.encode(payload),
+      #     content_type: encoder.content_type,
+      #   )
+      #
+      # @example Creating a Parcel with compressed MessagePack data
+      #   msgpack_data = MessagePack.pack(payload)
+      #   compressed_data = Zlib.gzip(msgpack_data)
+      #   parcel = Parcel.new(
+      #     compressed_data,
+      #     content_type: 'application/msgpack',
+      #     content_encoding: 'gzip',
+      #   )
+      #
+      # @example Accessing Parcel data in HTTP transport
+      #   # In HTTP adapters, Parcel metadata maps to HTTP headers:
+      #   env.headers['Content-Type'] = request.parcel.content_type
+      #   env.headers['Content-Encoding'] = request.parcel.content_encoding
+      #   env.body = request.parcel.data
+      #
+      # The content_type and content_encoding fields are optional but recommended:
+      # - Set them when creating the Parcel for automatic header management
+      # - Leave them nil for IO transports or when headers are managed elsewhere
+      # - HTTP transports use these to set appropriate request headers
+      #
+      # @see Core::Encoding::JSONEncoder for JSON encoding utilities
+      # @see Core::Transport::Request which wraps Parcels for transmission
+      class Parcel
+        # Creates a new Parcel with pre-encoded data.
+        #
+        # @param data [String] The already-encoded data (e.g., JSON string, MessagePack bytes)
+        # @param content_type [String, nil] MIME type of the data (e.g., 'application/json')
+        # @param content_encoding [String, nil] Encoding applied to data (e.g., 'gzip')
+        def initialize(data, content_type: nil, content_encoding: nil)
           @data = data
+          @content_type = content_type
+          @content_encoding = content_encoding
         end
 
-        def encode_with(encoder)
-          raise NotImplementedError
+        # @!attribute [r] data
+        #   @return [String] The encoded data payload
+        attr_reader :data
+
+        # Returns the length of the encoded data.
+        #
+        # @return [Integer] Number of bytes in the data
+        def length
+          data.length
         end
+
+        # @!attribute [r] content_type
+        #   @return [String, nil] MIME type of the data (e.g., 'application/json')
+        attr_reader :content_type
+
+        # @!attribute [r] content_encoding
+        #   @return [String, nil] Encoding applied to data (e.g., 'gzip')
+        attr_reader :content_encoding
       end
     end
   end

data/lib/datadog/core/transport/response.rb

@@ -34,7 +34,21 @@ module Datadog
         end
 
         def inspect
-          "#{self.class} ok?:#{ok?} unsupported?:#{unsupported?}, " \
+          maybe_code = if respond_to?(:code)
+            # Steep: `code` method may be defined by classes extending this module.
+            # There seem to be no annotation for this.
+            " code:#{code}," # steep:ignore NoMethod
+          end
+          payload = self.payload
+          # Truncation thresholds are arbitrary but we need to truncate the
+          # payload here because outputting multi-MB request body to the
+          # log is not useful.
+          #
+          # Note that payload can be nil here.
+          if payload && payload.length > 2000 # steep:ignore
+            payload = Utils::Truncation.truncate_in_middle(payload, 1500, 500) # steep:ignore
+          end
+          "#{self.class} ok?:#{ok?},#{maybe_code} unsupported?:#{unsupported?}, " \
             "not_found?:#{not_found?}, client_error?:#{client_error?}, " \
             "server_error?:#{server_error?}, internal_error?:#{internal_error?}, " \
             "payload:#{payload}"
@@ -55,6 +69,10 @@ module Datadog
           true
         end
 
+        def to_s
+          "#{self.class}, error_type:#{error.class} error:#{error}"
+        end
+
         def inspect
           "#{super}, error_type:#{error.class} error:#{error}"
         end

data/lib/datadog/core/transport/transport.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "http/client"
+
+module Datadog
+  module Core
+    module Transport
+      # Raised when configured with an unknown API version
+      class UnknownApiVersionError < StandardError
+        attr_reader :version
+
+        def initialize(version)
+          super
+
+          @version = version
+        end
+
+        def message
+          "No matching transport API for version #{version}!"
+        end
+      end
+
+      # Raised when the API verson to downgrade to does not map to a
+      # defined API.
+      class NoDowngradeAvailableError < StandardError
+        attr_reader :version
+
+        def initialize(version)
+          super
+
+          @version = version
+        end
+
+        def message
+          "No downgrade from transport API version #{version} is available!"
+        end
+      end
+
+      # Base class for transports.
+      class Transport
+        attr_reader :client, :apis, :default_api, :current_api_id, :logger
+
+        class << self
+          # The HTTP client class to use for requests, derived from
+          # Core::Transport::HTTP::Client.
+          #
+          # Important: this attribute is NOT inherited by derived classes -
+          # it must be set by every Transport class that wants to have a
+          # non-default HTTP::Client instance.
+          attr_accessor :http_client_class
+        end
+
+        def initialize(apis, default_api, logger:)
+          @apis = apis
+          @default_api = default_api
+          @logger = logger
+
+          set_api!(default_api)
+        end
+
+        def current_api
+          apis[current_api_id]
+        end
+
+        private
+
+        def set_api!(api_id)
+          raise UnknownApiVersionError, api_id unless apis.key?(api_id)
+
+          @current_api_id = api_id
+          client_class = self.class.http_client_class || Core::Transport::HTTP::Client
+          @client = client_class.new(current_api, logger: logger)
+        end
+
+        def downgrade?(response)
+          return false unless apis.fallbacks.key?(current_api_id)
+
+          response.not_found? || response.unsupported?
+        end
+
+        def downgrade!
+          downgrade_api_id = apis.fallbacks[current_api_id]
+          raise NoDowngradeAvailableError, current_api_id if downgrade_api_id.nil?
+
+          set_api!(downgrade_api_id)
+        end
+      end
+    end
+  end
+end