datadog 2.4.0 → 2.44.0

data/lib/datadog/kit/appsec/events/v2.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require_relative "../../identity"
+require_relative "../../../appsec/trace_keeper"
+
+module Datadog
+  module Kit
+    module AppSec
+      module Events
+        # The second version of Business Logic Events SDK
+        module V2
+          SIGNUP_EVENT = "users.signup"
+          LOGIN_SUCCESS_EVENT = "users.login.success"
+          LOGIN_FAILURE_EVENT = "users.login.failure"
+
+          TELEMETRY_METRICS_NAMESPACE = "appsec"
+          TELEMETRY_METRICS_SDK_EVENT = "sdk.event"
+          TELEMETRY_METRICS_SDK_VERSION = "v2"
+          TELEMETRY_METRICS_EVENTS_INTO_TYPES = {
+            LOGIN_SUCCESS_EVENT => "login_success",
+            LOGIN_FAILURE_EVENT => "login_failure",
+            SIGNUP_EVENT => "signup",
+          }.freeze
+
+          class << self
+            # Attach user login success information to the service entry span
+            # and trigger AppSec event processing.
+            #
+            # @param login [String] The user login (e.g., username or email).
+            # @param user_or_id [String, Hash<Symbol, String>] (optional) If a
+            #   String, considered as a user ID, if a Hash, considered as a user
+            #   attributes. The Hash must include `:id` as a key.
+            # @param metadata [Hash<Symbol, String>] Additional flat free-form
+            #   metadata to attach to the event.
+            #
+            # @example Login only
+            #   Datadog::Kit::AppSec::Events::V2.track_user_login_success('alice@example.com')
+            #
+            # @example Login and user attributes
+            #   Datadog::Kit::AppSec::Events::V2.track_user_login_success(
+            #     'alice@example.com',
+            #     { id: 'user-123', email: 'alice@example.com', name: 'Alice' },
+            #     ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
+            #   )
+            #
+            # @return [void]
+            def track_user_login_success(login, user_or_id = nil, metadata = {})
+              trace = service_entry_trace
+              span = service_entry_span
+
+              if trace.nil? || span.nil?
+                return Datadog.logger.warn(
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                )
+              end
+
+              raise TypeError, "`login` argument must be a String" unless login.is_a?(String)
+              raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)
+
+              user_attributes = build_user_attributes(user_or_id, login)
+
+              set_span_tags(span, metadata, namespace: LOGIN_SUCCESS_EVENT)
+              set_span_tags(span, user_attributes, namespace: "#{LOGIN_SUCCESS_EVENT}.usr")
+              span.set_tag("appsec.events.users.login.success.track", "true")
+              span.set_tag("_dd.appsec.events.users.login.success.sdk", "true")
+
+              ::Datadog::AppSec::TraceKeeper.keep!(trace)
+
+              record_event_telemetry_metric(LOGIN_SUCCESS_EVENT)
+              ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", LOGIN_SUCCESS_EVENT)
+
+              return Kit::Identity.set_user(trace, span, **user_attributes) if user_attributes.key?(:id)
+
+              # NOTE: This is a fallback for the case when we don't have an ID,
+              #       but need to trigger WAF.
+              user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, login)
+              ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
+            end
+
+            # Attach user login failure information to the service entry span
+            # and trigger AppSec event processing.
+            #
+            # @param login [String] The user login (e.g., username or email).
+            # @param user_exists [Boolean] Whether the user exists in the system.
+            # @param metadata [Hash<Symbol, String>] Additional flat free-form
+            #   metadata to attach to the event.
+            #
+            # @example Login only
+            #   Datadog::Kit::AppSec::Events::V2.track_user_login_failure('alice@example.com')
+            #
+            # @example With user existence and metadata
+            #   Datadog::Kit::AppSec::Events::V2.track_user_login_failure(
+            #     'alice@example.com',
+            #     true,
+            #     ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
+            #   )
+            #
+            # @return [void]
+            def track_user_login_failure(login, user_exists = false, metadata = {})
+              trace = service_entry_trace
+              span = service_entry_span
+
+              if trace.nil? || span.nil?
+                return Datadog.logger.warn(
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                )
+              end
+
+              raise TypeError, "`login` argument must be a String" unless login.is_a?(String)
+              raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)
+
+              unless user_exists.is_a?(TrueClass) || user_exists.is_a?(FalseClass)
+                raise TypeError, "`user_exists` argument must be a boolean"
+              end
+
+              set_span_tags(span, metadata, namespace: LOGIN_FAILURE_EVENT)
+              span.set_tag("appsec.events.users.login.failure.track", "true")
+              span.set_tag("_dd.appsec.events.users.login.failure.sdk", "true")
+              span.set_tag("appsec.events.users.login.failure.usr.login", login)
+              span.set_tag("appsec.events.users.login.failure.usr.exists", user_exists.to_s)
+
+              ::Datadog::AppSec::TraceKeeper.keep!(trace)
+
+              record_event_telemetry_metric(LOGIN_FAILURE_EVENT)
+              ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", LOGIN_FAILURE_EVENT)
+
+              user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, login)
+              ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
+            end
+
+            # Attach user signup information to the service entry span
+            # and trigger AppSec event processing.
+            #
+            # @param login [String] The user login (e.g., username or email).
+            # @param user_or_id [String, Hash<Symbol, String>] (optional) If a
+            #   String, considered as a user ID, if a Hash, considered as a user
+            #   attributes. The Hash must include `:id` as a key.
+            # @param metadata [Hash<Symbol, String>] Additional flat free-form
+            #   metadata to attach to the event.
+            #
+            # @example Login only
+            #   Datadog::Kit::AppSec::Events::V2.track_user_signup('alice@example.com')
+            #
+            # @example Login, user attributes, and metadata
+            #   Datadog::Kit::AppSec::Events::V2.track_user_signup(
+            #     'alice@example.com',
+            #     { id: 'user-123', email: 'alice@example.com', name: 'Alice' },
+            #     ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
+            #   )
+            #
+            # @return [void]
+            def track_user_signup(login, user_or_id = nil, metadata = {})
+              trace = service_entry_trace
+              span = service_entry_span
+
+              if trace.nil? || span.nil?
+                return Datadog.logger.warn(
+                  "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
+                )
+              end
+
+              raise TypeError, "`login` argument must be a String" unless login.is_a?(String)
+              raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)
+
+              user_attributes = build_user_attributes(user_or_id, login)
+
+              set_span_tags(span, metadata, namespace: SIGNUP_EVENT)
+              set_span_tags(span, user_attributes, namespace: "#{SIGNUP_EVENT}.usr")
+              span.set_tag("appsec.events.users.signup.track", "true")
+              span.set_tag("_dd.appsec.events.users.signup.sdk", "true")
+
+              ::Datadog::AppSec::TraceKeeper.keep!(trace)
+
+              record_event_telemetry_metric(SIGNUP_EVENT)
+
+              if user_attributes.key?(:id)
+                Kit::Identity.set_user(trace, span, **user_attributes)
+              else
+                # NOTE: {Datadog::Kit::Identity.set_user} requires an ID,
+                #       but WAF can evaluate login alone
+                user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, login)
+                ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
+              end
+            end
+
+            private
+
+            # NOTE: Current tracer implementation does not provide a way to
+            #       get the service entry span. This is a shortcut we take now.
+            def service_entry_trace
+              return Datadog::Tracing.active_trace unless Datadog::AppSec.active_context
+
+              Datadog::AppSec.active_context&.trace
+            end
+
+            # NOTE: Current tracer implementation does not provide a way to
+            #       get the service entry span. This is a shortcut we take now.
+            def service_entry_span
+              return Datadog::Tracing.active_span unless Datadog::AppSec.active_context
+
+              Datadog::AppSec.active_context&.span
+            end
+
+            def build_user_attributes(user_or_id, login)
+              raise TypeError, "`login` argument must be a String" unless login.is_a?(String)
+
+              case user_or_id
+              when nil
+                {login: login}
+              when String
+                {login: login, id: user_or_id}
+              when Hash
+                raise ArgumentError, "missing required user key `:id`" unless user_or_id.key?(:id)
+                raise TypeError, "user key `:id` must be a String" unless user_or_id[:id].is_a?(String)
+
+                user_or_id.merge(login: login)
+              else
+                raise TypeError, "`user_or_id` argument must be either String or Hash"
+              end
+            end
+
+            def set_span_tags(span, tags, namespace:)
+              tags.each do |name, value|
+                next if value.nil?
+
+                span.set_tag("appsec.events.#{namespace}.#{name}", value)
+              end
+            end
+
+            # TODO: In case if we need to introduce telemetry metrics to the SDK v1
+            #       or highly increase the number of metrics, this method should be
+            #       extracted into a proper module.
+            def record_event_telemetry_metric(event)
+              telemetry = ::Datadog.send(:components, allow_initialization: false)&.telemetry
+
+              if telemetry.nil?
+                return Datadog.logger.debug(
+                  "Kit::AppSec: Telemetry component is unavailable. Skip recording SDK metrics"
+                )
+              end
+
+              tags = {
+                event_type: TELEMETRY_METRICS_EVENTS_INTO_TYPES[event],
+                sdk_version: TELEMETRY_METRICS_SDK_VERSION,
+              }
+              telemetry.inc(TELEMETRY_METRICS_NAMESPACE, TELEMETRY_METRICS_SDK_EVENT, 1, tags: tags)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/kit/appsec/events.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-require_relative '../identity'
+require_relative "../identity"
+require_relative "../../appsec/trace_keeper"
 
 module Datadog
   module Kit
     module AppSec
       # Tracking events
       module Events
-        LOGIN_SUCCESS_EVENT = 'users.login.success'
-        LOGIN_FAILURE_EVENT = 'users.login.failure'
-        SIGNUP_EVENT = 'users.signup'
+        LOGIN_SUCCESS_EVENT = "users.login.success"
+        LOGIN_FAILURE_EVENT = "users.login.failure"
+        SIGNUP_EVENT = "users.signup"
+        USER_LOGIN_KEYS = ["usr.login", :"usr.login"].freeze
 
         class << self
           # Attach login success event information to the trace
@@ -27,14 +29,18 @@ module Datadog
           # @param others [Hash<String || Symbol, String>] Additional free-form
           #   event information to attach to the trace.
           def track_login_success(trace = nil, span = nil, user:, **others)
-            set_trace_and_span_context('track_login_success', trace, span) do |active_trace, active_span|
+            set_trace_and_span_context("track_login_success", trace, span) do |active_trace, active_span|
               user_options = user.dup
               user_id = user_options.delete(:id)
+              user_login = user_options[:login] || others[:"usr.login"] || others["usr.login"] || user_id
 
-              raise ArgumentError, 'missing required key: :user => { :id }' if user_id.nil?
+              raise ArgumentError, "missing required key: :user => { :id }" if user_id.nil?
 
+              others = others.reject { |key, _| USER_LOGIN_KEYS.include?(key) }
+              others[:"usr.login"] = user_login
               track(LOGIN_SUCCESS_EVENT, active_trace, active_span, **others)
 
+              user_options[:login] = user_login
               Kit::Identity.set_user(active_trace, active_span, id: user_id, **user_options)
             end
           end
@@ -54,11 +60,12 @@ module Datadog
           # @param others [Hash<String || Symbol, String>] Additional free-form
           #   event information to attach to the trace.
           def track_login_failure(trace = nil, span = nil, user_exists:, user_id: nil, **others)
-            set_trace_and_span_context('track_login_failure', trace, span) do |active_trace, active_span|
+            set_trace_and_span_context("track_login_failure", trace, span) do |active_trace, active_span|
+              others[:"usr.login"] = user_id if user_id && !others.key?(:"usr.login") && !others.key?("usr.login")
               track(LOGIN_FAILURE_EVENT, active_trace, active_span, **others)
 
-              active_span.set_tag('appsec.events.users.login.failure.usr.id', user_id) if user_id
-              active_span.set_tag('appsec.events.users.login.failure.usr.exists', user_exists)
+              active_span.set_tag("appsec.events.users.login.failure.usr.id", user_id) if user_id
+              active_span.set_tag("appsec.events.users.login.failure.usr.exists", user_exists)
             end
           end
 
@@ -77,14 +84,18 @@ module Datadog
           # @param others [Hash<String || Symbol, String>] Additional free-form
           #   event information to attach to the trace.
           def track_signup(trace = nil, span = nil, user:, **others)
-            set_trace_and_span_context('track_signup', trace, span) do |active_trace, active_span|
+            set_trace_and_span_context("track_signup", trace, span) do |active_trace, active_span|
               user_options = user.dup
               user_id = user_options.delete(:id)
+              user_login = user_options[:login] || others[:"usr.login"] || others["usr.login"] || user_id
 
-              raise ArgumentError, 'missing required key: :user => { :id }' if user_id.nil?
+              raise ArgumentError, "missing required key: :user => { :id }" if user_id.nil?
 
+              others = others.reject { |key, _| USER_LOGIN_KEYS.include?(key) }
+              others[:"usr.login"] = user_login
               track(SIGNUP_EVENT, active_trace, active_span, **others)
 
+              user_options[:login] = user_login
               Kit::Identity.set_user(trace, id: user_id, **user_options)
             end
           end
@@ -107,47 +118,49 @@ module Datadog
             if trace && span
               check_trace_span_integrity(trace, span)
 
-              span.set_tag("appsec.events.#{event}.track", 'true')
-              span.set_tag("_dd.appsec.events.#{event}.sdk", 'true')
+              span.set_tag("appsec.events.#{event}.track", "true")
+              span.set_tag("_dd.appsec.events.#{event}.sdk", "true")
 
               others.each do |k, v|
-                raise ArgumentError, 'key cannot be :track' if k.to_sym == :track
+                raise ArgumentError, "key cannot be :track" if k.to_sym == :track
 
                 span.set_tag("appsec.events.#{event}.#{k}", v) unless v.nil?
               end
 
-              trace.keep!
+              ::Datadog::AppSec::TraceKeeper.keep!(trace)
             else
-              set_trace_and_span_context('track', trace, span) do |active_trace, active_span|
-                active_span.set_tag("appsec.events.#{event}.track", 'true')
-                active_span.set_tag("_dd.appsec.events.#{event}.sdk", 'true')
+              set_trace_and_span_context("track", trace, span) do |active_trace, active_span|
+                active_span.set_tag("appsec.events.#{event}.track", "true")
+                active_span.set_tag("_dd.appsec.events.#{event}.sdk", "true")
 
                 others.each do |k, v|
-                  raise ArgumentError, 'key cannot be :track' if k.to_sym == :track
+                  raise ArgumentError, "key cannot be :track" if k.to_sym == :track
 
                   active_span.set_tag("appsec.events.#{event}.#{k}", v) unless v.nil?
                 end
 
-                active_trace.keep!
+                ::Datadog::AppSec::TraceKeeper.keep!(active_trace)
               end
             end
+
+            ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", event)
           end
 
           private
 
           def set_trace_and_span_context(method, trace = nil, span = nil)
-            if (appsec_scope = Datadog::AppSec.active_scope)
-              trace = appsec_scope.trace
-              span = appsec_scope.service_entry_span
+            if (appsec_context = Datadog::AppSec.active_context)
+              trace = appsec_context.trace
+              span = appsec_context.span
             end
 
             trace ||= Datadog::Tracing.active_trace
-            span ||=  trace && trace.active_span || Datadog::Tracing.active_span
+            span ||= trace&.active_span || Datadog::Tracing.active_span
 
             unless trace && span
               Datadog.logger.debug(
-                "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}"\
-                ' to track this events'
+                "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}" \
+                " to track this events"
               )
               return
             end

data/lib/datadog/kit/enable_core_dumps.rb

@@ -11,9 +11,9 @@ module Datadog
         current_size, maximum_size = Process.getrlimit(:CORE)
         core_pattern =
           begin
-            File.read('/proc/sys/kernel/core_pattern').strip
+            File.read("/proc/sys/kernel/core_pattern").strip
           rescue
-            '(Could not open /proc/sys/kernel/core_pattern)'
+            "(Could not open /proc/sys/kernel/core_pattern)"
           end
 
         enabled_status = "Maximum size: #{maximum_size} Output pattern: '#{core_pattern}'"
@@ -30,7 +30,7 @@ module Datadog
           Process.setrlimit(:CORE, maximum_size)
         rescue => e
           Kernel.warn(
-            "[datadog] Failed to enable core dumps. Cause: #{e.class.name} #{e.message} " \
+            "[datadog] Failed to enable core dumps. Cause: #{e.class}: #{e.message} " \
             "Location: #{Array(e.backtrace).first}"
           )
           return

data/lib/datadog/kit/identity.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../appsec/instrumentation/gateway/argument'
+require_relative "../appsec/instrumentation/gateway/argument"
 
 module Datadog
   module Kit
@@ -33,63 +33,70 @@ module Datadog
         # @param others [Hash<Symbol, String>] Additional free-form
         #   user information to attach to the trace.
         #
+        # rubocop:disable Metrics/AbcSize
         # rubocop:disable Metrics/CyclomaticComplexity
         # rubocop:disable Metrics/PerceivedComplexity
         def set_user(
           trace = nil, span = nil, id:, email: nil, name: nil, session_id: nil, role: nil, scope: nil, **others
         )
-          raise ArgumentError, 'missing required key: :id' if id.nil?
+          raise ArgumentError, "missing required key: :id" if id.nil?
 
           # enforce types
 
-          raise TypeError, ':id must be a String'         unless id.is_a?(String)
-          raise TypeError, ':email must be a String'      unless email.nil? || email.is_a?(String)
-          raise TypeError, ':name must be a String'       unless name.nil? || name.is_a?(String)
-          raise TypeError, ':session_id must be a String' unless session_id.nil? || session_id.is_a?(String)
-          raise TypeError, ':role must be a String'       unless role.nil? || role.is_a?(String)
-          raise TypeError, ':scope must be a String'      unless scope.nil? || scope.is_a?(String)
+          raise TypeError, ":id must be a String" unless id.is_a?(String)
+          raise TypeError, ":email must be a String" unless email.nil? || email.is_a?(String)
+          raise TypeError, ":name must be a String" unless name.nil? || name.is_a?(String)
+          raise TypeError, ":session_id must be a String" unless session_id.nil? || session_id.is_a?(String)
+          raise TypeError, ":role must be a String" unless role.nil? || role.is_a?(String)
+          raise TypeError, ":scope must be a String" unless scope.nil? || scope.is_a?(String)
 
           others.each do |k, v|
             raise TypeError, "#{k.inspect} must be a String" unless v.nil? || v.is_a?(String)
           end
 
-          set_trace_and_span_context('set_user', trace, span) do |_active_trace, active_span|
+          set_trace_and_span_context("set_user", trace, span) do |_active_trace, active_span|
             # set tags once data is known consistent
-            active_span.set_tag('usr.id', id)
-            active_span.set_tag('usr.email', email)           unless email.nil?
-            active_span.set_tag('usr.name', name)             unless name.nil?
-            active_span.set_tag('usr.session_id', session_id) unless session_id.nil?
-            active_span.set_tag('usr.role', role)             unless role.nil?
-            active_span.set_tag('usr.scope', scope)           unless scope.nil?
+            active_span.set_tag("usr.id", id)
+            active_span.set_tag("usr.email", email) unless email.nil?
+            active_span.set_tag("usr.name", name) unless name.nil?
+            active_span.set_tag("usr.session_id", session_id) unless session_id.nil?
+            active_span.set_tag("usr.role", role) unless role.nil?
+            active_span.set_tag("usr.scope", scope) unless scope.nil?
 
             others.each do |k, v|
               active_span.set_tag("usr.#{k}", v) unless v.nil?
             end
 
-            if Datadog::AppSec.active_scope
-              user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(id)
-              ::Datadog::AppSec::Instrumentation.gateway.push('identity.set_user', user)
+            if Datadog::AppSec.active_context
+              active_span.set_tag("_dd.appsec.user.collection_mode", "sdk")
+
+              user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(id, others[:login], session_id)
+              ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
             end
           end
         end
+        # rubocop:enable Metrics/AbcSize
         # rubocop:enable Metrics/PerceivedComplexity
         # rubocop:enable Metrics/CyclomaticComplexity
 
         private
 
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable Metrics/PerceivedComplexity
         def set_trace_and_span_context(method, trace = nil, span = nil)
-          if (appsec_scope = Datadog::AppSec.active_scope)
-            trace = appsec_scope.trace
-            span = appsec_scope.service_entry_span
+          if (appsec_context = Datadog::AppSec.active_context)
+            trace = appsec_context.trace
+            span = appsec_context.span
           end
 
           trace ||= Datadog::Tracing.active_trace
-          span ||= trace && trace.active_span || Datadog::Tracing.active_span
+          span ||= trace&.active_span || Datadog::Tracing.active_span
 
           unless trace && span
             Datadog.logger.debug(
-              "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}"\
-              ' to track this events'
+              "Tracing not enabled. Method ##{method} is a no-op. Please enable tracing if you want ##{method}" \
+              " to track this events"
             )
             return
           end
@@ -98,6 +105,9 @@ module Datadog
 
           yield(trace, span)
         end
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/CyclomaticComplexity
       end
     end
   end

data/lib/datadog/kit/tracing/method_tracer.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Needed since this file can be loaded without core
+require_relative "../../ruby_version"
+
+module Datadog
+  module Kit
+    module Tracing
+      # Trace methods easily
+      #
+      # Use as DSL module:
+      #
+      #     class MyClass
+      #       extend Datadog::Kit::Tracing::MethodTracer
+      #
+      #       def foo; 'hello'; end
+      #
+      #       trace_method :foo, span_name: 'optional_span_name'
+      #
+      #       def self.bar; 'hi'; end
+      #
+      #       trace_singleton_class_method :bar, span_name: 'optional_span_name'
+      #     end
+      #
+      # Or directly:
+      #
+      #     Datadog::Kit::Tracing::MethodTracer.trace_method(MyClass, :foo, span_name: 'optional_span_name')
+      #     Datadog::Kit::Tracing::MethodTracer.trace_method(MyClass.singleton_class, :bar, span_name: 'optional_span_name')
+      #
+      # Class argument is implicit via DSL usage; it is required otherwise, and
+      # can accept dynamic classes or modules.
+      #
+      # Span name is optional and defaults to 'Class#method' (or `Class.method`
+      # for singleton class methods) but is required if the class or module
+      # name is `nil`.
+      #
+      # Traced methods are only traced if already within a trace (i.e they do
+      # not create traces by themselves).
+      #
+      # Regular methods must be defined before `trace_method` can be called.
+      # Dynamic methods (e.g via `method_missing` or defined later) can be
+      # traced via `dynamic: true`, which relaxes method existence sanity
+      # checks, but will prevent preserving method visibility.
+      #
+      # Note that this uses `Module#prepend`, so do not use on methods that
+      # have been alias method chained or you risk an infinite recusion crash.
+      #
+      # @public_api
+      module MethodTracer
+        class << self
+          # Trace an instance method by module and name
+          #
+          # @param mod [Module] module or class containing the method to trace
+          # @param method_name [Symbol] name of the method to trace
+          # @param span_name [String, nil] optional span name (defaults to "Module#method")
+          # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+          # @return [void]
+          def trace_method(mod, method_name, span_name: nil, dynamic: false)
+            raise ArgumentError, "mod is not a module" unless mod.is_a?(Module)
+            raise ArgumentError, "ambiguous span name: provide one or define mod.name" if mod.name.nil? && span_name.nil?
+
+            is_private = mod.private_method_defined?(method_name)
+            is_protected = mod.protected_method_defined?(method_name)
+            is_defined = is_private || mod.method_defined?(method_name)
+
+            unless is_defined || dynamic
+              raise NoMethodError, "undefined method #{method_name.inspect} for class #{mod}"
+            end
+
+            hook_point = "#{mod.name}##{method_name}"
+            custom_span_name = span_name
+            span_name ||= hook_point
+
+            unless span_name.is_a?(String)
+              raise ArgumentError, "span name is not a String"
+            end
+
+            args = RubyVersion.is?(">= 2.7") ? "..." : "*args, &block"
+
+            hook_module = Module.new do
+              define_singleton_method(:inspect) do
+                suffix = custom_span_name ? ", #{custom_span_name.inspect}" : ""
+                name || "#<Datadog::Tracing::Kit::MethodTracer(#{method_name.inspect}#{suffix})>"
+              end
+
+              define_singleton_method(:to_s) do
+                suffix = custom_span_name ? ", #{custom_span_name.inspect}" : ""
+                name || "#<Datadog::Tracing::Kit::MethodTracer(#{method_name.inspect}#{suffix})>"
+              end
+
+              # this `eval` is safe:
+              # - `args` is static
+              # - `method_name` is validated by the `method_defined?` check
+              # - `span_name` is validated to be a String and inspected to be quoted
+              eval(<<-RUBY, nil, __FILE__, __LINE__ + 1) # standard:disable Security/Eval
+              def #{method_name}(#{args})
+                return super(#{args}) unless ::Datadog::Tracing.active_trace
+
+                ::Datadog::Tracing.trace(#{span_name.inspect}) { super(#{args}) }
+              end
+              RUBY
+
+              private method_name if is_private
+              protected method_name if is_protected
+            end
+
+            mod.prepend(hook_module)
+          end
+        end
+
+        # Trace a method by name in a module context
+        #
+        # @param method_name [Symbol] name of the method to trace
+        # @param span_name [String, nil] optional span name (defaults to "Module#method")
+        # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+        # @return [void]
+        def trace_method(method_name, span_name: nil, dynamic: false)
+          MethodTracer.trace_method(self, method_name, span_name: span_name, dynamic: dynamic)
+        end
+
+        # Trace a method by name in a module's singleton context (a.k.a "class method")
+        #
+        # @param method_name [Symbol] name of the method to trace
+        # @param span_name [String, nil] optional span name (defaults to "Module.method")
+        # @param dynamic [Boolean] if true, skip method existence check (for method_missing-handled methods)
+        # @return [void]
+        def trace_singleton_class_method(method_name, span_name: nil, dynamic: false)
+          span_name ||= "#{name}.#{method_name}" if respond_to?(:name)
+
+          MethodTracer.trace_method(singleton_class, method_name, span_name: span_name, dynamic: dynamic)
+        end
+      end
+    end
+  end
+end