datadog 2.39.0 → 2.47.0

data/lib/datadog/di/el/compiler.rb

@@ -16,8 +16,42 @@ module Datadog
       #
       # @api private
       class Compiler
+        # Compiles +ast+ into eval'able Ruby source.
+        #
+        # Returns the compiled source and companion compiled Regexp
+        # objects.
+        #
+        # @param ast [untyped] expression AST from the probe definition.
+        # @return [Array(String, Array<Regexp>)] the compiled Ruby source and
+        #   the precompiled Regexps, indexed in the order the compiled code
+        #   references them.
         def compile(ast)
-          compile_partial(ast)
+          regexps = []
+          code = compile_partial(ast, regexps)
+          [code, regexps]
+        end
+
+        # Returns the identifier that +ast+ directly references at its top
+        # level, so the message path can redact direct references the same
+        # way snapshots redact by name.
+        #
+        # @param ast [untyped] top-level expression AST from a probe definition.
+        # @return [String, nil] the variable name for a `ref`/`iref`, the field
+        #   name for a `getmember`, or the string key for an `index`; nil when
+        #   the top-level expression is not a direct reference.
+        def redaction_identifier(ast)
+          return nil unless Hash === ast && ast.length == 1
+
+          entry = ast.first
+          return nil if entry.nil?
+
+          op, target = entry
+          case op
+          when "ref"
+            target if String === target
+          when "getmember", "index"
+            target[1] if Array === target && target.length == 2 && String === target[1]
+          end
         end
 
         private
@@ -37,9 +71,13 @@ module Datadog
           len isEmpty isUndefined
         ].freeze # steep:ignore IncompatibleAssignment
 
+        # `matches` is also a two-argument method but is special-cased in
+        # #compile_partial so that regular expressions can be precompiled
+        # once, so it is not listed here.
+        #
         # Steep: https://github.com/soutaro/steep/issues/363
         TWO_ARG_METHODS = %w[
-          startsWith endsWith contains matches
+          startsWith endsWith contains
           getmember index instanceof
         ].freeze # steep:ignore IncompatibleAssignment
 
@@ -49,13 +87,18 @@ module Datadog
           "or" => "||",
         }.freeze
 
-        def compile_partial(ast)
+        # @param ast [untyped] AST node to compile.
+        # @param regexps [Array<Regexp>] output array that collects the
+        #   companion precompiled Regexp objects.
+        # @return [String] compiled Ruby source for +ast+.
+        def compile_partial(ast, regexps)
           case ast
           when Hash
-            if ast.length != 1
+            entry = ast.first
+            if ast.length != 1 || entry.nil?
               raise DI::Error::InvalidExpression, "Expected hash of length 1: #{ast}"
             end
-            op, target = ast.first
+            op, target = entry
             case op
             when "ref"
               unless String === target
@@ -94,20 +137,33 @@ module Datadog
               end
             when *SINGLE_ARG_METHODS
               method_name = op.gsub(/[A-Z]/) { |m| "_#{m.downcase}" }
-              "#{method_name}(#{compile_partial(target)}, '#{var_name_maybe(target)}')"
+              "#{method_name}(#{compile_partial(target, regexps)}, '#{var_name_maybe(target)}')"
+            when "matches"
+              unless Array === target && target.length == 2
+                raise DI::Error::InvalidExpression, "Improper matches syntax"
+              end
+              first, second = target
+              if String === second
+                # Match against a literal regular expression (string).
+                index = precompile_regexp(second, regexps)
+                "matches_compiled(#{compile_partial(first, regexps)}, #{index})"
+              else
+                # Match against a (complex) expression.
+                "matches(#{compile_partial(first, regexps)}, (#{compile_partial(second, regexps)}))"
+              end
             when *TWO_ARG_METHODS
               method_name = op.gsub(/[A-Z]/) { |m| "_#{m.downcase}" }
               unless Array === target && target.length == 2
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               first, second = target
-              "#{method_name}(#{compile_partial(first)}, (#{compile_partial(second)}))"
+              "#{method_name}(#{compile_partial(first, regexps)}, (#{compile_partial(second, regexps)}))"
             when *MULTI_ARG_METHODS.keys
               unless Array === target && target.length >= 1
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               compiled_targets = target.map do |item|
-                "(#{compile_partial(item)})"
+                "(#{compile_partial(item, regexps)})"
               end
               compiled_op = MULTI_ARG_METHODS[op]
               "(#{compiled_targets.join(" #{compiled_op} ")})"
@@ -115,18 +171,21 @@ module Datadog
               unless Array === target && target.length == 3
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
-              "#{op}(#{target.map { |arg| "(#{compile_partial(arg)})" }.join(", ")})"
+              "#{op}(#{target.map { |arg| "(#{compile_partial(arg, regexps)})" }.join(", ")})"
             when "not"
-              "!(#{compile_partial(target)})"
+              "!(#{compile_partial(target, regexps)})"
             when *OPERATORS.keys
               unless Array === target && target.length == 2
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               first, second = target
               operator = OPERATORS.fetch(op)
-              "(#{compile_partial(first)}) #{operator} (#{compile_partial(second)})"
+              "(#{compile_partial(first, regexps)}) #{operator} (#{compile_partial(second, regexps)})"
             when "any", "all", "filter"
-              "#{op}(#{compile_partial(target.first)}) { |current_item, current_key, current_value| #{compile_partial(target.last)} }"
+              unless Array === target && target.length == 2
+                raise DI::Error::InvalidExpression, "Improper #{op} syntax"
+              end
+              "#{op}(#{compile_partial(target.first, regexps)}) { |current_item, current_key, current_value| #{compile_partial(target.last, regexps)} }"
             else
               raise DI::Error::InvalidExpression, "Unknown operation: #{op}"
             end
@@ -162,6 +221,23 @@ module Datadog
         def escape(needle)
           needle.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("#") { "\\#" }
         end
+
+        # Compile a literal regular expression +regexp_str+ at
+        # instrumentation time. Append it to +regexps+, returning its index for
+        # Evaluator#matches_compiled to look up.
+        #
+        # @param regexp_str [String] regular expression source.
+        # @param regexps [Array<Regexp>] output array to append the compiled
+        #   regexp to.
+        # @return [Integer] index into +regexps+.
+        # @raise [DI::Error::InvalidExpression] if +needle+ is not a valid regexp.
+        def precompile_regexp(regexp_str, regexps)
+          index = regexps.length
+          regexps << Evaluator.compile_regexp(regexp_str)
+          index
+        rescue RegexpError => exc
+          raise DI::Error::InvalidExpression, "Invalid regular expression in matches: #{exc.class}: #{exc.message}"
+        end
       end
     end
   end

data/lib/datadog/di/el/evaluator.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "../../ruby_version"
+
+require "timeout" if Datadog::RubyVersion.is?("< 3.2")
+
 module Datadog
   module DI
     module EL
@@ -7,6 +11,20 @@ module Datadog
       #
       # @api private
       class Evaluator
+        # Maximum wall-clock time allowed for evaluating a single `matches`
+        # operator.
+        MATCHES_TIMEOUT_SECONDS = 0.5
+
+        # @param regexps [Array<Regexp>] Regexps precompiled from literal
+        #   `matches` patterns, looked up by index by #matches_compiled.
+        #    Empty when the expression has no `matches` pattern with
+        #    a direct regular expression argument.
+        def initialize(regexps = [])
+          @regexps = regexps
+        end
+
+        attr_reader :regexps
+
         def ref(var)
           @context.fetch(var)
         end
@@ -48,10 +66,72 @@ module Datadog
           end
         end
 
+        # Build a Regexp from a pattern string. On Ruby 3.2+ the per-match
+        # timeout (MATCHES_TIMEOUT_SECONDS) is baked into the compiled
+        # Regexp via the in-engine `timeout:` keyword, which interrupts the
+        # matcher at every backtrack step and reliably bounds matcher
+        # runtime regardless of pattern shape. On older Rubies the Regexp
+        # carries no timeout; the bound is applied at match time by
+        # #bounded_match? instead.
+        #
+        # @param needle [String] regexp source.
+        # @return [Regexp] compiled regexp, with baked-in timeout on Ruby 3.2+.
+        if Datadog::RubyVersion.is?(">= 3.2")
+          def self.compile_regexp(needle)
+            Regexp.new(needle, timeout: MATCHES_TIMEOUT_SECONDS)
+          end
+        else
+          def self.compile_regexp(needle)
+            Regexp.compile(needle)
+          end
+        end
+
+        # Match +haystack+ against a regexp whose needle is computed at
+        # evaluation time, so the Regexp cannot be precompiled. Literal needles are
+        # precompiled by the Compiler and dispatched to #matches_compiled.
+        #
+        # @param haystack [String] string to match against.
+        # @param needle [String] regexp source.
+        # @return [Boolean] whether the haystack matches the regexp.
+        # @raise [Regexp::TimeoutError] (Ruby 3.2+) regexp engine exceeded MATCHES_TIMEOUT_SECONDS.
+        # @raise [Timeout::Error] (Ruby < 3.2) Timeout.timeout fired.
         def matches(haystack, needle)
-          re = Regexp.compile(needle)
-          !!(haystack =~ re)
+          bounded_match?(Evaluator.compile_regexp(needle), haystack)
+        end
+
+        # Match +haystack+ against a Regexp precompiled at expression-compile
+        # time, looked up by index in +regexps+.
+        #
+        # @param haystack [String] string to match against.
+        # @param index [Integer] position of the precompiled Regexp in +regexps+.
+        # @return [Boolean] whether the haystack matches the regexp.
+        # @raise [Regexp::TimeoutError] (Ruby 3.2+) regexp engine exceeded MATCHES_TIMEOUT_SECONDS.
+        # @raise [Timeout::Error] (Ruby < 3.2) Timeout.timeout fired.
+        def matches_compiled(haystack, index)
+          bounded_match?(regexps.fetch(index), haystack)
+        end
+
+        # Match +haystack+ against +re+, bounded at MATCHES_TIMEOUT_SECONDS
+        # wall-clock.
+        #
+        # @param re [Regexp] regexp to match against.
+        # @param haystack [String] string to match against.
+        # @return [Boolean] whether the haystack matches the regexp.
+        if Datadog::RubyVersion.is?(">= 3.2")
+          def bounded_match?(re, haystack)
+            # Uses Regexp#match? rather than =~ so that the
+            # thread-local match data ($~, $1, ...) is not mutated as a side
+            # effect of DI expression evaluation.
+            re.match?(haystack)
+          end
+        else
+          def bounded_match?(re, haystack)
+            Timeout.timeout(MATCHES_TIMEOUT_SECONDS) do
+              re.match?(haystack)
+            end
+          end
         end
+        private :bounded_match?
 
         def getmember(object, field)
           object.instance_variable_get("@#{field}")

data/lib/datadog/di/el/expression.rb

@@ -7,12 +7,22 @@ module Datadog
       #
       # @api private
       class Expression
-        def initialize(dsl_expr, compiled_expr)
+        # @param dsl_expr [String] human-readable DSL form, kept for debugging.
+        # @param compiled_expr [String] Ruby source produced by Compiler#compile.
+        # @param regexps [Array<Regexp>] precompiled `matches` regexps (see
+        #   Compiler#precompile_regexp), the second element returned by
+        #   Compiler#compile.
+        # @param redaction_identifier [String, nil] the identifier this
+        #   expression directly references at its top level (see
+        #   Compiler#redaction_identifier); nil when it is not a direct
+        #   reference.
+        def initialize(dsl_expr, compiled_expr, regexps: [], redaction_identifier: nil)
           unless String === compiled_expr
             raise ArgumentError, "compiled_expr must be a string"
           end
 
           @dsl_expr = dsl_expr
+          @redaction_identifier = redaction_identifier
 
           cls = Class.new(Evaluator)
           cls.class_exec do
@@ -23,11 +33,12 @@ module Datadog
               end
             RUBY
           end
-          @evaluator = cls.new
+          @evaluator = cls.new(regexps)
         end
 
         attr_reader :dsl_expr
         attr_reader :evaluator
+        attr_reader :redaction_identifier
 
         def evaluate(context)
           @evaluator.evaluate(context)

data/lib/datadog/di/evaluation_failure.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    # An expression evaluation failure reported in a snapshot's evaluation
+    # errors: the expression that failed and the error description.
+    # @api private
+    class EvaluationFailure
+      # Initializes the failure.
+      #
+      # @param expr [String] name of the capture expression, or source of the condition or template expression, that failed to evaluate or serialize
+      # @param message [String] error description of the failed evaluation
+      # @return [void]
+      def initialize(expr:, message:)
+        @expr = expr
+        @message = message
+      end
+
+      # The name of the capture expression, or the source of the condition or
+      # template expression, that failed to evaluate or serialize.
+      # @return [String]
+      attr_reader :expr
+
+      # @return [String] the error description of the failed evaluation
+      attr_reader :message
+    end
+  end
+end

data/lib/datadog/di/guardrails_telemetry/reason.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    class GuardrailsTelemetry
+      # Canonical guardrails reason codes. Codes
+      # shared with the other Datadog tracers keep the exact shared
+      # spelling; codes with no shared counterpart use the Ruby tracer's
+      # own name for the same decision.
+      module Reason
+        # Skip reason emitted when a probe firing is rejected by the
+        # probe's own rate limiter.
+        RATE_LIMIT_PROBE = "rateLimitProbe"
+
+        # Skip reason emitted when a probe firing is rejected by the
+        # process-wide rate limiter.
+        RATE_LIMIT_GLOBAL = "rateLimitGlobal"
+
+        # Skip reason emitted when a capture expression evaluation exceeds
+        # the capture time budget.
+        EVALUATION_TIMEOUT = "evaluationTimeout"
+
+        # Skip reason named in the +di: debug log when a condition-evaluation
+        # failure notification is rejected by the per-probe limiter.
+        EVALUATION_ERROR_THROTTLED = "evaluationErrorThrottled"
+
+        # Skip reason naming the per-invocation DI time budget guardrail
+        # decision.
+        BUDGET_EXCEEDED_INVOCATION = "budgetExceededInvocation"
+
+        # Skip reason naming the process-wide DI time budget guardrail
+        # decision.
+        BUDGET_EXCEEDED_GLOBAL = "budgetExceededGlobal"
+
+        # Skip and drop reason emitted when an event is discarded at a
+        # full worker queue.
+        QUEUE_FULL = "queueFull"
+
+        # Skip and drop reason naming the queue high-watermark guardrail
+        # decision.
+        QUEUE_HIGH_WATERMARK = "queueHighWatermark"
+
+        # Drop reason emitted when a snapshot exceeds the serialized
+        # payload limit.
+        PAYLOAD_TOO_LARGE = "payloadTooLarge"
+
+        # Drop reason naming the batch byte-cap guardrail decision.
+        BATCH_BYTES_EXCEEDED = "batchBytesExceeded"
+
+        # Capture-incomplete reason emitted when a capture or
+        # serialization runtime exception ends the capture of a value
+        # early.
+        RUNTIME_ERROR = "runtimeError"
+
+        # Capture-incomplete reason emitted when a value is not captured
+        # because the capture time budget expired while it was being
+        # serialized.
+        CAPTURE_TIMEOUT = "timeout"
+
+        # Capture-incomplete reason emitted when a value at the maximum
+        # capture depth is not captured.
+        DEPTH = "depth"
+
+        # Capture-incomplete reason emitted when an object with more
+        # fields than the capture limit is partially captured.
+        FIELD_COUNT = "fieldCount"
+
+        # Capture-incomplete reason emitted when a collection with more
+        # items than the capture limit is partially captured.
+        COLLECTION_SIZE = "collectionSize"
+
+        # Capture-incomplete reason emitted when a captured string is
+        # trimmed to the capture limit.
+        STRING_LENGTH = "stringLength"
+
+        # Capture-incomplete reason for an early-capture cause with no
+        # more specific code.
+        OTHER = "other"
+
+        # The skip reasons the events.skipped metric tags with the firing
+        # probe's id; every other skip reason names a process-wide
+        # decision and carries no probe id.
+        PROBE_SCOPED_REASONS = [RATE_LIMIT_PROBE, EVALUATION_TIMEOUT].freeze
+      end
+    end
+  end
+end

data/lib/datadog/di/guardrails_telemetry.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "fatal_exceptions"
+require_relative "guardrails_telemetry/reason"
+
+module Datadog
+  module DI
+    # Telemetry namespace for DI metrics, shared with the other tracers.
+    # The telemetry wire name is
+    # +dd.instrumentation_telemetry_data.debugger.*+.
+    TELEMETRY_NAMESPACE = "debugger"
+
+    # Telemetry reporter for the DI guardrails: the reason codes and the
+    # metric emitters.
+    class GuardrailsTelemetry
+      # Skip count metric name, emitted under +DI::TELEMETRY_NAMESPACE+.
+      EVENTS_SKIPPED = "events.skipped"
+      # Drop count metric name, emitted under +DI::TELEMETRY_NAMESPACE+.
+      EVENTS_DROPPED = "events.dropped"
+      # Incomplete-capture count metric name, emitted under +DI::TELEMETRY_NAMESPACE+.
+      CAPTURE_INCOMPLETE = "capture.incomplete"
+
+      # Queue byte-count metric, emitted under +DI::TELEMETRY_NAMESPACE+.
+      QUEUE_DROPPED_BYTES = "guardrails.queue.dropped_bytes"
+
+      # Tag value for probes that capture a full snapshot.
+      EVENT_TYPE_SNAPSHOT = "snapshot"
+      # Tag value for probes that capture evaluated log output.
+      EVENT_TYPE_LOG = "log"
+
+      # Initializes the reporter.
+      #
+      # @param settings [Datadog::Core::Configuration::Settings] tracer settings the propagation escape hatch is read from
+      # @param logger [DI::Logger] logger for contained emission failures
+      # @param telemetry [Datadog::Core::Telemetry::Component, nil] component the guardrails metrics are emitted through
+      def initialize(settings:, logger:, telemetry:)
+        @settings = settings
+        @logger = logger
+        @telemetry = telemetry
+        @skipped_tags_memo = {}
+        @dropped_tags_memo = {}
+        @capture_incomplete_tags_memo = {}
+      end
+
+      # The tracer settings.
+      # @return [Datadog::Core::Configuration::Settings]
+      attr_reader :settings
+      # The logger.
+      # @return [DI::Logger]
+      attr_reader :logger
+      # The component the guardrails metrics are emitted through.
+      # @return [Datadog::Core::Telemetry::Component, nil]
+      attr_reader :telemetry
+      # The memo of frozen tag hashes for emitted skip metrics without
+      # +probe_id+, keyed by reason and event type.
+      # @return [Hash{String => Hash{String => Hash{Symbol => String}}}]
+      attr_reader :skipped_tags_memo
+      # The memo of frozen tag hashes for emitted drop metrics, keyed by
+      # reason and event type.
+      # @return [Hash{String => Hash{String => Hash{Symbol => String}}}]
+      attr_reader :dropped_tags_memo
+      # The memo of frozen tag hashes for emitted incomplete-capture
+      # metrics, keyed by reason and event type.
+      # @return [Hash{String => Hash{String => Hash{Symbol => String}}}]
+      attr_reader :capture_incomplete_tags_memo
+
+      # Returns the canonical event_type tag for a probe, derived from
+      # whether the probe captures a full snapshot.
+      #
+      # @param probe [Probe] the probe whose firing is being tagged
+      # @return [String] EVENT_TYPE_SNAPSHOT or EVENT_TYPE_LOG
+      def self.probe_event_type_tag(probe)
+        probe.capture_snapshot? ? EVENT_TYPE_SNAPSHOT : EVENT_TYPE_LOG
+      end
+
+      # Emits the canonical +debugger.events.skipped+ count metric for a
+      # probe firing a guardrail rejected.
+      #
+      # @param reason [String] a GuardrailsTelemetry::Reason constant naming the skip cause
+      # @param probe [Probe] the probe whose firing was rejected
+      # @return [void]
+      def skipped(reason:, probe:)
+        probe_id = probe.id if Reason::PROBE_SCOPED_REASONS.include?(reason)
+        inc_metric(
+          DI::TELEMETRY_NAMESPACE, EVENTS_SKIPPED, 1,
+          tags: skipped_tags(reason, self.class.probe_event_type_tag(probe), probe_id),
+        )
+        nil
+      end
+
+      # Emits the canonical +debugger.events.dropped+ count metric, and,
+      # when +bytes+ is provided, the +guardrails.queue.dropped_bytes+ count
+      # metric.
+      #
+      # @param reason [String] a GuardrailsTelemetry::Reason constant naming the drop cause
+      # @param event_type [String] the canonical event_type tag value
+      # @param bytes [Integer, nil] encoded bytes discarded, when the drop site knows the count
+      # @return [void]
+      def dropped(reason:, event_type:, bytes: nil)
+        tags = dropped_tags(reason, event_type)
+        inc_metric(DI::TELEMETRY_NAMESPACE, EVENTS_DROPPED, 1, tags: tags)
+        inc_metric(DI::TELEMETRY_NAMESPACE, QUEUE_DROPPED_BYTES, bytes, tags: tags) if bytes
+        nil
+      end
+
+      # Emits the canonical +debugger.capture.incomplete+ count metric for
+      # a capture limit enforced on a snapshot that is still sent.
+      #
+      # @param reason [String] a GuardrailsTelemetry::Reason constant naming the enforced capture limit
+      # @param event_type [String] the canonical event_type tag value
+      # @return [void]
+      def capture_incomplete(reason:, event_type:)
+        inc_metric(
+          DI::TELEMETRY_NAMESPACE, CAPTURE_INCOMPLETE, 1,
+          tags: capture_incomplete_tags(reason, event_type),
+        )
+        nil
+      end
+
+      private
+
+      # Emits a guardrails count metric.
+      #
+      # @param namespace [String] telemetry namespace the metric is emitted under
+      # @param metric_name [String] guardrails metric name
+      # @param value [Integer] increment count, or the discarded byte count
+      # @param tags [Hash{Symbol => String}] frozen metric tags for the emission
+      # @return [void]
+      def inc_metric(namespace, metric_name, value, tags:)
+        telemetry&.inc(namespace, metric_name, value, tags: tags)
+      rescue Exception => exc # standard:disable Lint/RescueException
+        Datadog::DI.reraise_if_fatal(exc)
+        raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+        report_emission_failure(namespace, metric_name, exc)
+        nil
+      end
+
+      def report_emission_failure(namespace, metric_name, exc)
+        logger.debug { "di: error emitting #{namespace}.#{metric_name} metric: #{exc.class}: #{exc.message}" }
+        begin
+          telemetry&.report(exc, description: "Error emitting #{namespace}.#{metric_name} metric")
+        rescue Exception => nested_exc # standard:disable Lint/RescueException
+          Datadog::DI.reraise_if_fatal(nested_exc)
+          logger.debug do
+            "di: error reporting #{namespace}.#{metric_name} metric emission failure: " \
+              "#{nested_exc.class}: #{nested_exc.message}"
+          end
+        end
+        nil
+      end
+
+      # Returns the frozen tags for a skip emission. Emissions without
+      # +probe_id+ are memoized; probe-scoped emissions allocate one
+      # frozen hash per emission: remote configuration adds and removes
+      # probes frequently, and a per-probe-id memo would grow without
+      # bound over the process lifetime.
+      #
+      # @param reason [String] the skip reason
+      # @param event_type [String] the canonical event_type tag value
+      # @param probe_id [String, nil] the rejected probe's id
+      # @return [Hash{Symbol => String}] the frozen skip-metric tags
+      def skipped_tags(reason, event_type, probe_id)
+        return {reason: reason, event_type: event_type, probe_id: probe_id}.freeze if probe_id
+
+        memoized_tags(skipped_tags_memo, reason, event_type)
+      end
+
+      # Returns the frozen tags for a drop emission, memoized per
+      # (reason, event_type) pair.
+      #
+      # @param reason [String] the drop reason
+      # @param event_type [String] the canonical event_type tag value
+      # @return [Hash{Symbol => String}] the frozen drop-metric tags
+      def dropped_tags(reason, event_type)
+        memoized_tags(dropped_tags_memo, reason, event_type)
+      end
+
+      # Returns the frozen tags for an incomplete-capture emission,
+      # memoized per (reason, event_type) pair.
+      #
+      # @param reason [String] the enforced capture limit
+      # @param event_type [String] the canonical event_type tag value
+      # @return [Hash{Symbol => String}] the frozen incomplete-capture metric tags
+      def capture_incomplete_tags(reason, event_type)
+        memoized_tags(capture_incomplete_tags_memo, reason, event_type)
+      end
+
+      # Returns the frozen tags memoized per (reason, event_type) pair,
+      # so a repeated emission allocates no tag hash. The memo is
+      # lock-free: a racy first write can only discard a duplicate
+      # frozen hash.
+      #
+      # @param memo [Hash{String => Hash{String => Hash{Symbol => String}}}] the emission-kind memo to index
+      # @param reason [String] the emission reason
+      # @param event_type [String] the canonical event_type tag value
+      # @return [Hash{Symbol => String}] the frozen metric tags
+      def memoized_tags(memo, reason, event_type)
+        reason_memos = memo[reason] ||= {}
+        reason_memos[event_type] ||= {reason: reason, event_type: event_type}.freeze
+      end
+    end
+  end
+end