datadog 2.4.0 → 2.44.0

data/lib/datadog/di/logger.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Datadog
+  module DI
+    # Logger facade to add the +trace+ method.
+    #
+    # @api private
+    class Logger
+      extend Forwardable
+
+      def initialize(settings, target)
+        @settings = settings
+        @target = target
+      end
+
+      attr_reader :settings
+      attr_reader :target
+
+      def_delegators :target, :debug
+
+      def trace
+        if settings.dynamic_instrumentation.internal.trace_logging
+          debug { yield }
+        end
+      end
+    end
+  end
+end

data/lib/datadog/di/preload.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Require 'datadog/di/preload' early in the application boot process to
+# enable dynamic instrumentation for third-party libraries used by the
+# application.
+
+require_relative "base"
+
+# Code tracking is required for line probes to work; see the comments
+# on the activate_tracking methods in di.rb for further details.
+#
+# Unlike di.rb which conditionally activates tracking only if the
+# DD_DYNAMIC_INSTRUMENTATION_ENABLED environment variable is set, this file
+# always activates tracking. This is because this file is explicitly loaded
+# by customer applications for the purpose of enabling code tracking
+# early in application boot process (i.e., before datadog library itself
+# is loaded).
+Datadog::DI.activate_tracking

data/lib/datadog/di/probe.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "utils"
 require_relative "../core/rate_limiter"
 
 module Datadog
@@ -16,7 +17,7 @@ module Datadog
     # and remote config code must be prepared to deal with exceptions
     # raised by Probe constructor in particular. Therefore, Probe constructor
     # will raise an exception if it determines that there is not enough
-    # information (or confilcting information) in the arguments to create a
+    # information (or conflicting information) in the arguments to create a
     # functional probe, and upstream code is tasked with not spamming logs
     # with notifications of such errors (and potentially limiting the
     # attempts to construct probe from a given payload).
@@ -31,19 +32,50 @@ module Datadog
     #
     # @api private
     class Probe
+      KNOWN_TYPES = %i[log].freeze
+
+      EVALUATE_AT_VALUES = %i[entry exit].freeze
+
       def initialize(id:, type:,
         file: nil, line_no: nil, type_name: nil, method_name: nil,
-        template: nil, capture_snapshot: false, max_capture_depth: nil, rate_limit: nil)
+        template: nil, template_segments: nil,
+        capture_snapshot: false, max_capture_depth: nil,
+        max_capture_attribute_count: nil,
+        max_capture_collection_size: nil, max_capture_string_length: nil,
+        capture_expressions: [],
+        evaluate_at: nil,
+        condition: nil,
+        rate_limit: nil)
         # Perform some sanity checks here to detect unexpected attribute
         # combinations, in order to not do them in subsequent code.
-        if line_no && method_name
-          raise ArgumentError, "Probe contains both line number and method name: #{id}"
+        unless KNOWN_TYPES.include?(type)
+          raise ArgumentError, "Unknown probe type: #{type}"
+        end
+
+        # Probe should be inferred to be a line probe if the specification
+        # contains a line number. This how Java tracer works and Go tracer
+        # is implementing the same behavior, and Go will have all 3 fields
+        # (file path, line number and method name) for line probes.
+        # Do not raise if line number and method name both exist - instead
+        # treat the probe as a line probe.
+        #
+        # In the future we want to provide type name and method name to line
+        # probes, so that the library can verify that the instrumented line
+        # is in the method that the frontend showed to the user when the
+        # user created the probe.
+
+        if line_no && !file
+          raise ArgumentError, "Probe contains line number but not file: #{id}"
         end
 
         if type_name && !method_name || method_name && !type_name
           raise ArgumentError, "Partial method probe definition: #{id}"
         end
 
+        if line_no.nil? && method_name.nil?
+          raise ArgumentError, "Unhandled probe type: neither method nor line probe: #{id}"
+        end
+
         @id = id
         @type = type
         @file = file
@@ -51,19 +83,35 @@ module Datadog
         @type_name = type_name
         @method_name = method_name
         @template = template
+        @template_segments = template_segments
         @capture_snapshot = !!capture_snapshot
         @max_capture_depth = max_capture_depth
-
-        # These checks use instance methods that have more complex logic
-        # than checking a single argument value. To avoid duplicating
-        # the logic here, use the methods and perform these checks after
-        # instance variable assignment.
-        unless method? || line?
-          raise ArgumentError, "Unhandled probe type: neither method nor line probe: #{id}"
+        @max_capture_attribute_count = max_capture_attribute_count
+        @max_capture_collection_size = max_capture_collection_size
+        @max_capture_string_length = max_capture_string_length
+        @capture_expressions = capture_expressions || []
+        evaluate_at = :exit if evaluate_at.nil?
+        unless EVALUATE_AT_VALUES.include?(evaluate_at)
+          raise ArgumentError, "Unknown evaluate_at value: #{evaluate_at.inspect} (expected one of #{EVALUATE_AT_VALUES.inspect})"
         end
+        @evaluate_at = evaluate_at
+        @condition = condition
 
-        @rate_limit = rate_limit || (@capture_snapshot ? 1 : 5000)
+        @rate_limit = rate_limit || (capturing? ? 1 : 5000)
         @rate_limiter = Datadog::Core::TokenBucket.new(@rate_limit)
+
+        # At most one report per second.
+        # We create the rate limiter here even though it may never be used,
+        # to avoid having to synchronize the creation since method probes
+        # can be executed on multiple threads concurrently (even if line
+        # probes are never executed concurrently since those are done in a
+        # trace point).
+        if condition
+          @condition_evaluation_failed_rate_limiter = Datadog::Core::TokenBucket.new(1)
+        end
+
+        @emitting_notified = false
+        @enabled = true
       end
 
       attr_reader :id
@@ -73,33 +121,93 @@ module Datadog
       attr_reader :type_name
       attr_reader :method_name
       attr_reader :template
+      attr_reader :template_segments
+
+      # The compiled condition for the probe, as a String.
+      attr_reader :condition
 
       # Configured maximum capture depth. Can be nil in which case
       # the global default will be used.
       attr_reader :max_capture_depth
 
+      # Configured maximum capture attribute count. Can be nil in which case
+      # the global default will be used.
+      attr_reader :max_capture_attribute_count
+
+      attr_reader :max_capture_collection_size
+
+      attr_reader :max_capture_string_length
+
+      attr_reader :capture_expressions
+
+      attr_reader :evaluate_at
+
       # Rate limit in effect, in invocations per second. Always present.
       attr_reader :rate_limit
 
       # Rate limiter object. For internal DI use only.
       attr_reader :rate_limiter
 
+      # Rate limiter object for sending snapshots with evaluation errors
+      # for when probe condition evaluation fails.
+      # This rate limit is separate from the "base" rate limit for the probe
+      # because when the condition evaluation succeeds we want the "base"
+      # rate limit applied, not tainted by any evaluation errors
+      # (for example, the condition can be highly selective, and when it
+      # does not hold the evaluation may fail - we don't want to use up the
+      # probe rate limit for the errors).
+      attr_reader :condition_evaluation_failed_rate_limiter
+
       def capture_snapshot?
         @capture_snapshot
       end
 
+      def capture_expressions?
+        !@capture_expressions.empty?
+      end
+
+      # Whether this probe captures user data, either as a full snapshot
+      # or via capture expressions.
+      #
+      # @return [Boolean]
+      def capturing?
+        capture_snapshot? || capture_expressions?
+      end
+
+      def evaluate_at_entry?
+        evaluate_at == :entry
+      end
+
+      # Capture-expression mode: the probe captures expressions but not a full
+      # snapshot. Snapshot capture serializes its own values, so expression
+      # capture only runs when a snapshot is not being taken.
+      def capture_expressions_only?
+        capture_expressions? && !capture_snapshot?
+      end
+
+      def capture_entry_expressions?
+        capture_expressions_only? && evaluate_at_entry?
+      end
+
+      def snapshot_serializer_limits(settings)
+        CaptureLimits.resolve(expr_limits: nil, probe: self, settings: settings)
+      end
+
       # Returns whether the probe is a line probe.
       #
       # Method probes may still specify a file name (to aid in locating the
       # method or for stack traversal purposes?), therefore we do not check
       # for file name/path presence here and just consider the line number.
       def line?
-        !line_no.nil?
+        # Constructor checks that file is given if line number is given,
+        # but for safety, check again here since we somehow got a probe with
+        # a line number but no file in the wild.
+        !!(file && line_no)
       end
 
       # Returns whether the probe is a method probe.
       def method?
-        !!(type_name && method_name)
+        line_no.nil?
       end
 
       # Returns the line number associated with the probe, raising
@@ -116,6 +224,20 @@ module Datadog
         line_no
       end
 
+      # Returns the method name associated with the probe, raising
+      # Error::MissingMethodName if the probe does not have a method name
+      # associated with it.
+      #
+      # This method is used by instrumentation driver to ensure a method name
+      # that is passed into the instrumentation logic is actually a method name
+      # and not nil.
+      def method_name!
+        if method_name.nil?
+          raise Error::MissingMethodName, "Probe #{id} does not have a method name associated with it"
+        end
+        method_name
+      end
+
       # Source code location of the probe, for diagnostic reporting.
       def location
         if method?
@@ -128,6 +250,58 @@ module Datadog
           raise NotImplementedError
         end
       end
+
+      # Returns whether the provided +path+ matches the user-designated
+      # file (of a line probe).
+      #
+      # Delegates to Utils.path_can_match_spec? which performs fuzzy
+      # matching. See the comments in utils.rb for details.
+      def file_matches?(path)
+        if path.nil?
+          raise ArgumentError, "Cannot match against a nil path"
+        end
+        unless file
+          raise ArgumentError, "Probe does not have a file to match against"
+        end
+        Utils.path_can_match_spec?(path, file)
+      end
+
+      # Instrumentation module for method probes.
+      attr_accessor :instrumentation_module
+
+      # Line trace point for line probes. Normally this would be a targeted
+      # trace point.
+      attr_accessor :instrumentation_trace_point
+
+      # Actual path to the file instrumented by the probe, for line probes,
+      # when code tracking is available and line trace point is targeted.
+      # For untargeted line trace points instrumented path will be nil.
+      attr_accessor :instrumented_path
+
+      # TODO emitting_notified reads and writes should in theory be locked,
+      # however since DI is only implemented for MRI in practice the missing
+      # locking should not cause issues.
+      attr_writer :emitting_notified
+      def emitting_notified?
+        !!@emitting_notified
+      end
+
+      def executed_on_line?
+        !!(defined?(@executed_on_line) && @executed_on_line)
+      end
+
+      def executed_on_line!
+        # TODO lock?
+        @executed_on_line = true
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def disable!
+        @enabled = false
+      end
     end
   end
 end

data/lib/datadog/di/probe_builder.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
+# rubocop:disable Lint/AssignmentInCondition
+
 require_relative "probe"
+require_relative "capture_expression"
+require_relative "capture_limits"
+require_relative "el"
 
 module Datadog
   module DI
@@ -17,25 +22,149 @@ module Datadog
     #
     # @api private
     module ProbeBuilder
-      module_function def build_from_remote_config(config)
+      # Steep: https://github.com/soutaro/steep/issues/363
+      PROBE_TYPES = { # steep:ignore IncompatibleAssignment
+        "LOG_PROBE" => :log,
+      }.freeze
+
+      module_function
+
+      CAPTURE_EXPRESSION_NAME_PATTERN = /\A[a-zA-Z0-9_?]+\z/
+
+      EVALUATE_AT_STRINGS = {
+        "ENTRY" => :entry,
+        "EXIT" => :exit,
+        "DEFAULT" => :exit,
+      }.freeze
+
+      def build_from_remote_config(config, logger:)
         # The validations here are not yet comprehensive.
+        type = config.fetch("type")
+        type_symbol = PROBE_TYPES[type] or raise ArgumentError, "Unrecognized probe type: #{type}"
+        cond = if cond_spec = config["when"]
+          unless cond_spec["dsl"] && cond_spec["json"]
+            raise ArgumentError, "Malformed condition specification for probe: #{config}"
+          end
+          compiled, regexps = EL::Compiler.new.compile(cond_spec["json"])
+          EL::Expression.new(cond_spec["dsl"], compiled, regexps: regexps)
+        end
+        capture_expressions = build_capture_expressions(config["captureExpressions"])
+        capture_expressions = dedup_capture_expressions(capture_expressions, config["id"], logger)
+        if !!config["captureSnapshot"] && !capture_expressions.empty?
+          logger.debug do
+            "di: probe #{config["id"]}: captureSnapshot=true wins over captureExpressions (n=#{capture_expressions.size})"
+          end
+        end
         Probe.new(
           id: config.fetch("id"),
-          type: config.fetch("type"),
+          type: type_symbol,
           file: config["where"]&.[]("sourceFile"),
           # Sometimes lines are sometimes received as an array of nil
           # for some reason.
           line_no: config["where"]&.[]("lines")&.compact&.map(&:to_i)&.first,
           type_name: config["where"]&.[]("typeName"),
           method_name: config["where"]&.[]("methodName"),
+          # We should not be using the template for anything - we instead
+          # use +segments+ - but keep the template for debugging.
           template: config["template"],
+          template_segments: build_template_segments(config["segments"]),
           capture_snapshot: !!config["captureSnapshot"],
           max_capture_depth: config["capture"]&.[]("maxReferenceDepth"),
+          max_capture_attribute_count: config["capture"]&.[]("maxFieldCount"),
+          max_capture_collection_size: config["capture"]&.[]("maxCollectionSize"),
+          max_capture_string_length: config["capture"]&.[]("maxLength"),
+          capture_expressions: capture_expressions,
+          evaluate_at: parse_evaluate_at(config["evaluateAt"], config["id"], logger),
           rate_limit: config["sampling"]&.[]("snapshotsPerSecond"),
+          condition: cond,
         )
       rescue KeyError => exc
-        raise ArgumentError, "Malformed remote configuration entry for probe: #{exc.class}: #{exc}: #{config}"
+        raise ArgumentError, "Malformed remote configuration entry for probe: #{exc.class}: #{exc.message}: #{config}"
+      end
+
+      def build_capture_expressions(raw)
+        return [] if raw.nil?
+        unless Array === raw
+          raise ArgumentError, "captureExpressions must be an array, got: #{raw.class}"
+        end
+        return [] if raw.empty?
+        raw.map do |entry|
+          unless Hash === entry
+            raise ArgumentError, "captureExpressions entry must be a hash, got: #{entry.class}"
+          end
+          name = entry["name"]
+          unless String === name && CAPTURE_EXPRESSION_NAME_PATTERN.match?(name)
+            raise ArgumentError, "captureExpressions entry name missing or invalid (must match #{CAPTURE_EXPRESSION_NAME_PATTERN.inspect}): #{name.inspect}"
+          end
+          expr_spec = entry["expr"]
+          unless Hash === expr_spec && expr_spec["dsl"] && expr_spec["json"]
+            raise ArgumentError, "captureExpressions entry #{name}: missing or malformed expr"
+          end
+          compiled, regexps = EL::Compiler.new.compile(expr_spec["json"])
+          expr = EL::Expression.new(expr_spec["dsl"], compiled, regexps: regexps)
+          limits = build_capture_limits(entry["capture"])
+          CaptureExpression.new(name: name, expr: expr, limits: limits)
+        end
+      end
+
+      def dedup_capture_expressions(capture_expressions, probe_id, logger)
+        return capture_expressions if capture_expressions.size < 2
+        by_name = {}
+        capture_expressions.each do |capture_expression|
+          by_name[capture_expression.name] = capture_expression
+        end
+        return capture_expressions if by_name.size == capture_expressions.size
+        logger.debug do
+          "di: probe #{probe_id}: collapsed duplicate captureExpressions names, kept last per name (#{capture_expressions.size} -> #{by_name.size})"
+        end
+        by_name.values
+      end
+
+      def build_capture_limits(raw)
+        return nil if raw.nil?
+        unless Hash === raw
+          raise ArgumentError, "capture-expression entry capture must be a hash, got: #{raw.class}"
+        end
+        CaptureLimits.new(
+          max_reference_depth: raw["maxReferenceDepth"],
+          max_collection_size: raw["maxCollectionSize"],
+          max_length: raw["maxLength"],
+          max_field_count: raw["maxFieldCount"],
+        )
+      end
+
+      def parse_evaluate_at(raw, probe_id, logger)
+        return :exit if raw.nil?
+        EVALUATE_AT_STRINGS[raw] || begin
+          logger.debug do
+            "di: probe #{probe_id}: unrecognized evaluateAt value #{raw.inspect}, defaulting to :exit"
+          end
+          :exit
+        end
+      end
+
+      def build_template_segments(segments)
+        segments&.map do |segment|
+          if Hash === segment
+            if str = segment["str"]
+              str
+            elsif ast = segment["json"]
+              unless dsl = segment["dsl"]
+                raise ArgumentError, "Missing dsl for json in segment: #{segment}"
+              end
+              compiler = EL::Compiler.new
+              compiled, regexps = compiler.compile(ast)
+              EL::Expression.new(dsl, compiled, regexps: regexps, redaction_identifier: compiler.redaction_identifier(ast))
+            else
+              # TODO report to telemetry?
+            end
+          else
+            # TODO report to telemetry?
+          end
+        end&.compact
       end
     end
   end
 end
+
+# rubocop:enable Lint/AssignmentInCondition

data/lib/datadog/di/probe_file_loader/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    module ProbeFileLoader
+      # Railtie class initializes dynamic instrumentation contrib code
+      # in Rails environments.
+      class Railtie < Rails::Railtie
+        initializer "datadog.dynamic_instrumentation.load_probe_file" do |app|
+          ProbeFileLoader.load_now
+        end
+      end
+    end
+  end
+end

data/lib/datadog/di/probe_file_loader.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "fatal_exceptions"
+
+module Datadog
+  module DI
+    module ProbeFileLoader
+      module_function def load_now_or_later
+        if Datadog::Core::Contrib::Rails::Utils.railtie_supported?
+          Datadog.logger.debug("di: loading probe_file_loader/railtie")
+          require_relative "probe_file_loader/railtie"
+        else
+          load_now
+        end
+      end
+
+      # This method can be called more than once, to attempt to load
+      # DI components that depend on third-party libraries after additional
+      # dependencies are loaded (or potentially loaded).
+      module_function def load_now
+        should_propagate = false
+
+        probe_file_path = DATADOG_ENV["DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE"]
+        if probe_file_path.nil? || probe_file_path.empty?
+          return
+        end
+
+        # We want to initialize the component tree here if it was not already
+        # initialized.
+        component = Datadog::DI.component
+        return unless component
+
+        begin
+          probe_specs = File.open(probe_file_path) do |f|
+            # The probe file should contain an array, JSON.parse does not work
+            JSON.load(f) # standard:disable Security/JSONLoad
+          end
+
+          probe_specs.each do |probe_spec|
+            probe = component.parse_probe_spec_and_notify(probe_spec)
+            component.logger.debug { "di: received #{probe.type} probe at #{probe.location} (#{probe.id}) via probe file: #{probe_file_path}" }
+
+            begin
+              component.probe_manager.add_probe(probe)
+            rescue DI::Error::DITargetNotInRegistry => exc
+              component.telemetry&.report(exc, description: "Line probe is targeting a loaded file that is not in code tracker")
+
+              payload = component.probe_notification_builder.build_errored(probe, exc)
+              component.probe_notifier_worker.add_status(payload, probe: probe)
+            rescue Exception => exc # standard:disable Lint/RescueException
+              Datadog::DI.reraise_if_fatal(exc)
+              raise if component.settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+              component.logger.debug { "di: unhandled exception adding #{probe.type} probe at #{probe.location} (#{probe.id}) in DI probe file loader: #{exc.class}: #{exc.message}" }
+              component.telemetry&.report(exc, description: "Unhandled exception adding probe in DI probe file loader")
+
+              # TODO test this path
+              payload = component.probe_notification_builder.build_errored(probe, exc)
+              component.probe_notifier_worker.add_status(payload, probe: probe)
+            end
+          end
+        rescue Exception => exc # standard:disable Lint/RescueException
+          Datadog::DI.reraise_if_fatal(exc)
+          if component.settings.dynamic_instrumentation.internal.propagate_all_exceptions
+            should_propagate = true
+            raise
+          end
+
+          component.logger.debug { "di: unhandled exception handling a probe in DI probe file loader: #{exc.class}: #{exc.message}" }
+          component.telemetry&.report(exc, description: "Unhandled exception handling probe in DI probe file loader")
+        end
+      rescue Exception => exc # standard:disable Lint/RescueException
+        Datadog::DI.reraise_if_fatal(exc)
+        # We should generally never get here, but if component tree
+        # initialization fails for some unexpected reason, don't nuke
+        # the customer application.
+        #
+        # For the same reason, we do not check
+        # component.settings.dynamic_instrumentation.internal.propagate_all_exceptions
+        # here again, but rely on the local variable storing that value.
+        raise if should_propagate
+      end
+    end
+  end
+end