datadog 2.28.0 → 2.41.0

data/lib/datadog/open_feature/hooks/span_enrichment_hook/span_enrichment_state.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "set"
+require "json"
+
+require_relative "codec"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Per-root-span state. Enforces the frozen limits, dedupes serial
+        # ids structurally via a Set, and renders the three `ffe_*` tag shapes.
+        #
+        # Not internally synchronized: every method is only ever called while the
+        # owning `SpanEnrichmentHook`'s mutex is held (capture, encode, cleanup),
+        # so the state stays a plain object and the lock provides the
+        # consistent snapshot at encode time.
+        class SpanEnrichmentState
+          def initialize
+            @serial_ids = Set.new
+            @subjects = {} # sha256hex => Set<int>
+            @defaults = {} # flag_key => String
+          end
+
+          def add_serial_id(serial_id)
+            return if @serial_ids.size >= MAX_SERIAL_IDS
+
+            @serial_ids.add(serial_id)
+          end
+
+          # Subject serial ids are NOT required to be a subset of the flag set:
+          # the frozen cross-SDK wire contract does not mandate `subjects ⊆ flags`,
+          # so a subject may reference a serial id that the independent 200-flag cap
+          # dropped from `ffe_flags_enc`. This mirrors the reference implementation
+          # and every other SDK; the caps (200 flags, 10 subjects, 20 experiments)
+          # are applied independently on purpose.
+          def add_subject(targeting_key, serial_id)
+            hashed = Codec.hash_targeting_key(targeting_key)
+            existing = @subjects[hashed]
+
+            if existing
+              return if existing.size >= MAX_EXPERIMENTS_PER_SUBJECT
+
+              existing.add(serial_id)
+            elsif @subjects.size >= MAX_SUBJECTS
+              nil
+            else
+              @subjects[hashed] = Set[serial_id]
+            end
+          end
+
+          # `value` is the flag's resolved runtime-default — any OpenFeature
+          # value type (String, boolean, number, or a structured Hash/Array).
+          # Non-strings are JSON-encoded (not `to_s`) so a structured default is
+          # captured faithfully rather than as Ruby's `inspect` form (e.g.
+          # `{"a"=>1}`, which is not valid JSON). The result is a bounded
+          # diagnostic PREVIEW, not a round-trippable value: it is truncated to
+          # the frozen 64-char cap, so a long JSON string is intentionally left
+          # as a non-parseable prefix. The backend treats this field as a
+          # display string, so a clipped value is acceptable.
+          def add_default(flag_key, value)
+            return if @defaults.key?(flag_key) # first-wins
+            return if @defaults.size >= MAX_DEFAULTS
+
+            value_str = value.is_a?(String) ? value : JSON.generate(value)
+            # Slicing is by codepoint, so a multibyte UTF-8 character is never
+            # split; `|| value_str` keeps the value non-nil for the zero-start slice.
+            @defaults[flag_key] = value_str[0, MAX_DEFAULT_VALUE_LENGTH] || value_str
+          end
+
+          # Subjects are intentionally not checked: a subject is only ever added
+          # alongside a serial id, so serial ids cover that case.
+          def has_data?
+            @serial_ids.any? || @defaults.any?
+          end
+
+          def to_span_tags
+            tags = {}
+            tags[TAG_FLAGS_ENC] = Codec.encode_delta_varint(@serial_ids) if @serial_ids.any?
+
+            if @subjects.any?
+              encoded_subjects = {}
+              @subjects.each { |hashed, ids| encoded_subjects[hashed] = Codec.encode_delta_varint(ids) }
+              tags[TAG_SUBJECTS_ENC] = JSON.generate(encoded_subjects)
+            end
+
+            tags[TAG_RUNTIME_DEFAULTS] = JSON.generate(@defaults) if @defaults.any?
+
+            tags
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/hooks/span_enrichment_hook/span_enrichment_state_store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "span_enrichment_state"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      class SpanEnrichmentHook
+        # Maps each trace operation to its `SpanEnrichmentState`, keyed WEAKLY by
+        # object identity. Using `ObjectSpace::WeakMap` means an
+        # abandoned trace (root span never finishes) cannot pin its state:
+        # once the trace operation is unreachable the entry is collected. The
+        # state (the WeakMap *value*, which `WeakMap` would otherwise also
+        # collect once no strong ref remains) is kept alive for the trace's
+        # lifetime by the `span_before_finish` subscription closure, which is held
+        # by `trace_op.events`. So state lives exactly as long as the trace and
+        # dies with it.
+        #
+        # All access is serialized by the owning hook's mutex; the WeakMap itself
+        # is not thread-safe under concurrent mutation.
+        class SpanEnrichmentStateStore
+          def initialize
+            @states = ObjectSpace::WeakMap.new
+          end
+
+          def [](trace_op)
+            @states[trace_op]
+          end
+
+          def []=(trace_op, state)
+            @states[trace_op] = state
+          end
+
+          def delete(trace_op)
+            # `ObjectSpace::WeakMap#delete` was only added in Ruby 3.3; this gem
+            # supports Ruby 2.5+, so overwrite the slot with nil instead so a stale
+            # entry is never re-read after the root finishes. The slot itself is
+            # reclaimed when the trace operation is collected.
+            @states[trace_op] = nil
+          end
+
+          def clear!
+            @states = ObjectSpace::WeakMap.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/hooks/span_enrichment_hook.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "span_enrichment_hook/codec"
+require_relative "span_enrichment_hook/span_enrichment_state"
+require_relative "span_enrichment_hook/span_enrichment_state_store"
+
+module Datadog
+  module OpenFeature
+    module Hooks
+      # Captures feature-flag evaluation metadata and writes contract-conformant
+      # `ffe_*` tags onto the local root APM span when it finishes.
+      #
+      # The wire format is a fixed cross-SDK contract. The encoding (ULEB128
+      # delta-varint + base64), the per-trace aggregation limits, the runtime-default
+      # detection (missing variant) and the SHA256 subject hashing must be
+      # reproduced exactly so the backend decodes tags identically regardless of
+      # which language SDK emitted them.
+      #
+      # Dispatch:
+      #   Enrichment is driven DIRECTLY from `Provider#evaluate` (see `#capture`),
+      #   not through an OpenFeature hook. This is the only path that works on
+      #   every supported SDK version, so the capture happens on the provider
+      #   evaluation thread rather than a hook callback.
+      #
+      # Lifecycle:
+      #   - `#capture` runs on every evaluation. It resolves the local root span
+      #     off the active trace, lazily creates the per-root `SpanEnrichmentState`,
+      #     and on the first capture for a trace subscribes to that trace's
+      #     `span_before_finish` event. The subscription closure captures the
+      #     state strongly and is held by `trace_op.events`, so the state lives
+      #     exactly as long as the trace operation (the weak store key) — when the
+      #     trace is GC'd both die together (no leak even if the root never finishes).
+      #   - When the local root span is about to finish, the accumulated tags are
+      #     written via `span.set_tag` and the per-root state is deleted.
+      #   - `#shutdown` clears all accumulated state (provider-close cleanup).
+      #
+      # Thread-safety:
+      #   Concurrent evaluations (on different threads) can target the same active
+      #   trace. The GVL does NOT make the compound operations here safe
+      #   (fetch-or-create, subscribe-once, mutate-while-encoding), so all store /
+      #   subscription / state access is serialized through a single
+      #   `Mutex`, and the finish-time encode takes the snapshot under that lock.
+      #
+      # When the gate is off the hook is never constructed (see
+      # `Component#create_span_enrichment_hook`), so there is zero idle per-span
+      # overhead.
+      class SpanEnrichmentHook
+        # Fixed cross-SDK contract limits. No env-var knobs.
+        MAX_SERIAL_IDS = 200
+        MAX_SUBJECTS = 10
+        MAX_EXPERIMENTS_PER_SUBJECT = 20
+        MAX_DEFAULTS = 5
+        MAX_DEFAULT_VALUE_LENGTH = 64
+
+        TAG_FLAGS_ENC = "ffe_flags_enc"
+        TAG_SUBJECTS_ENC = "ffe_subjects_enc"
+        TAG_RUNTIME_DEFAULTS = "ffe_runtime_defaults"
+
+        def initialize(span_enrichment_state_store, logger:)
+          @store = span_enrichment_state_store
+          @mutex = Mutex.new
+          @active = true
+          @logger = logger
+        end
+
+        # Direct dispatch from the Datadog provider evaluation path. Takes only
+        # primitives so it does not depend on any OpenFeature SDK object shape and
+        # works on every supported SDK version. Never raises — flag evaluation and
+        # the trace pipeline must not be broken by enrichment.
+        #
+        # @param flag_key [String] the evaluated flag key
+        # @param variant [String, nil] the resolved variant (nil/empty => runtime default)
+        # @param value [Object] the resolved value (used for runtime-default capture)
+        # @param serial_id [Integer, nil] the split serial id, when assigned
+        # @param do_log [Boolean] whether logging/exposure is authorized for this subject
+        # @param targeting_key [String, nil] the raw targeting key (hashed before emit)
+        def capture(flag_key:, variant:, value:, serial_id:, do_log:, targeting_key:)
+          trace_op = Datadog::Tracing.active_trace
+          return unless trace_op
+
+          @mutex.synchronize do
+            if serial_id.nil?
+              if variant.nil? || variant.empty?
+                # Runtime default: detected by a missing variant (never a reason enum).
+                state_for(trace_op).add_default(flag_key, value)
+              end
+            else
+              state = state_for(trace_op)
+              state.add_serial_id(serial_id)
+              # Skip empty targeting keys: SHA256('') would collide every
+              # anonymous/missing subject under one bogus hash, corrupting
+              # subject-level attribution.
+              state.add_subject(targeting_key, serial_id) if do_log && targeting_key && !targeting_key.empty?
+            end
+          end
+        rescue => e
+          @logger.debug { "Error capturing span enrichment: #{e.class}: #{e.message}" }
+        end
+
+        # Provider-close cleanup: mark the hook inactive and drop all accumulated
+        # state. State is dropped, not flushed, on purpose: each state only
+        # becomes a set of tags when ITS OWN root span finishes, and at
+        # provider-close time those roots are still open — there is no valid
+        # target to flush to, and writing partial tags onto in-flight spans
+        # would emit incomplete data (and double-write once the root finished).
+        # A trace that already subscribed still holds its state via the
+        # `span_before_finish` closure, so clearing `@active` (checked in
+        # `write_tags_on_root`) is what actually prevents a stale write after
+        # shutdown. Per-trace subscriptions die with their trace operations, so
+        # there is nothing else to unsubscribe.
+        def shutdown
+          @mutex.synchronize do
+            @active = false
+            @store.clear!
+          end
+        end
+
+        private
+
+        # Lazily create the per-root state and, on first capture for a trace,
+        # subscribe to that trace's span lifecycle so we can write tags when the
+        # local root span finishes. MUST be called with `@mutex` held.
+        def state_for(trace_op)
+          state = @store[trace_op]
+          return state if state
+
+          state = SpanEnrichmentState.new
+          @store[trace_op] = state
+          subscribe_root_finish(trace_op, state)
+          state
+        end
+
+        # MUST be called with `@mutex` held. The subscription closure captures
+        # `state` strongly; since the closure is retained by
+        # `trace_op.events`, this keeps the WeakMap value alive for the trace's
+        # lifetime (and lets both be collected together when the trace is GC'd).
+        def subscribe_root_finish(trace_op, state)
+          events = trace_op.send(:events)
+          # `span_before_finish` fires `(span_op, trace_op)` while the span can
+          # still be enriched (before it is finalized into an immutable Span).
+          # The block is the tracer-callback boundary and runs long after
+          # `#capture` returns, so it rescues on its own — enrichment must never
+          # raise into the trace pipeline. (Errors setting up the subscription
+          # here propagate to `#capture`'s rescue, since this runs under it.)
+          events.span_before_finish.subscribe do |span_op, finishing_trace_op|
+            # `span_before_finish` fires for EVERY span in the trace, and in any
+            # nested trace the child spans finish before the local root. Only the
+            # local root's finish may write tags AND clean up per-trace state:
+            # acting on a child finish would wipe the state before the root
+            # is written. Guard here so `write_tags_on_root` (and its cleanup) only
+            # ever runs for the local root.
+            next unless span_op.equal?(finishing_trace_op.send(:root_span))
+
+            write_tags_on_root(span_op, finishing_trace_op, state)
+          rescue => e
+            @logger.debug { "Error writing span enrichment tags: #{e.class}: #{e.message}" }
+          end
+        end
+
+        def write_tags_on_root(span_op, trace_op, state)
+          # Snapshot the tags under the lock so a concurrent `#capture` on another
+          # thread cannot mutate the state's Sets/Hashes while we encode.
+          tags = @mutex.synchronize do
+            # After shutdown the store is cleared, but this trace's subscription
+            # closure still holds the state; write only while active so a provider
+            # close/reconfigure never emits stale `ffe_*` tags on an open trace.
+            if @active && state.has_data?
+              state.to_span_tags
+            else
+              {}
+            end
+          ensure
+            # The caller only invokes this on the local root's finish, so cleanup
+            # runs exactly once per trace. In an `ensure` so abandoned state is
+            # still freed if encoding ever raises.
+            @store.delete(trace_op)
+          end
+
+          tags.each { |key, value| span_op.set_tag(key, value) }
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/metrics/flag_eval_metrics.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Datadog
+  module OpenFeature
+    module Metrics
+      # Records flag evaluation metrics via OpenTelemetry
+      class FlagEvalMetrics
+        METER_NAME = "ddtrace.openfeature"
+        METRIC_NAME = "feature_flag.evaluations"
+        METRIC_UNIT = "{evaluation}"
+        METRIC_DESCRIPTION = "Number of feature flag evaluations"
+
+        ATTR_FLAG_KEY = "feature_flag.key"
+        ATTR_VARIANT = "feature_flag.result.variant"
+        ATTR_REASON = "feature_flag.result.reason"
+        ATTR_ALLOCATION_KEY = "feature_flag.result.allocation_key"
+        ATTR_ERROR_TYPE = "error.type"
+
+        DEFAULT_ERROR_TYPE = "general"
+
+        ERROR_TYPE_MAP = {
+          "FLAG_NOT_FOUND" => "flag_not_found",
+          "TYPE_MISMATCH" => "type_mismatch",
+          "PARSE_ERROR" => "parse_error",
+          "PROVIDER_NOT_READY" => "provider_not_ready",
+          "TARGETING_KEY_MISSING" => "targeting_key_missing",
+          "INVALID_CONTEXT" => "invalid_context",
+          "PROVIDER_FATAL" => "provider_fatal",
+          "GENERAL" => DEFAULT_ERROR_TYPE,
+        }.freeze
+
+        # Reasons that should not include allocation_key in metrics
+        EXCLUDE_ALLOCATION_KEY_REASONS = %w[error default disabled].freeze
+
+        def initialize(telemetry:, logger:)
+          @telemetry = telemetry
+          @logger = logger
+          @enabled = Datadog.configuration.opentelemetry.metrics.enabled
+          @counter = nil
+          @mutex = Mutex.new
+
+          unless @enabled
+            @logger.debug { "OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled" }
+          end
+        end
+
+        def record(flag_key, variant:, reason:, error_code: nil, allocation_key: nil)
+          return unless @enabled
+
+          counter = get_or_create_counter
+          return unless counter
+
+          attributes = build_attributes(
+            flag_key,
+            variant: variant,
+            reason: reason,
+            error_code: error_code,
+            allocation_key: allocation_key,
+          )
+          counter.add(1, attributes: attributes)
+        rescue => e
+          @logger.debug { "OpenFeature: Failed to record evaluation metric: #{e.class}: #{e.message}" }
+          @telemetry.report(e, description: "OpenFeature: Failed to record evaluation metric")
+        end
+
+        private
+
+        # Counter is created lazily because OTel SDK may not be initialized
+        # when the OpenFeature component is created.
+        def get_or_create_counter
+          @mutex.synchronize do
+            return @counter if @counter
+
+            meter_provider = get_or_initialize_meter_provider
+            return unless meter_provider
+
+            meter = meter_provider.meter(METER_NAME)
+            @counter = meter.create_counter(
+              METRIC_NAME,
+              unit: METRIC_UNIT,
+              description: METRIC_DESCRIPTION
+            )
+          end
+        rescue => e
+          @logger.debug { "OpenFeature: Failed to create metrics counter: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # Fetch an available OTel meter provider, initializing if needed.
+        # Returns the meter provider if available, nil otherwise.
+        def get_or_initialize_meter_provider
+          meter_provider = defined?(::OpenTelemetry) ? ::OpenTelemetry.meter_provider : nil
+          return meter_provider if sdk_meter_provider?(meter_provider)
+
+          @logger.debug { "OpenFeature: Initializing OTel meter provider directly" }
+          require "opentelemetry-metrics-sdk"
+          require "datadog/opentelemetry/metrics"
+          Datadog::OpenTelemetry::Metrics.initialize!(Datadog.send(:components))
+
+          meter_provider = ::OpenTelemetry.meter_provider
+          sdk_meter_provider?(meter_provider) ? meter_provider : nil
+        rescue LoadError => e
+          @logger.debug { "OpenFeature: Failed to initialize OTel metrics: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        def sdk_meter_provider?(meter_provider)
+          return false if meter_provider.nil?
+          return false unless defined?(::OpenTelemetry::SDK::Metrics::MeterProvider)
+
+          meter_provider.is_a?(::OpenTelemetry::SDK::Metrics::MeterProvider)
+        end
+
+        def build_attributes(flag_key, variant:, reason:, error_code:, allocation_key:)
+          reason_downcase = normalize_reason(reason)
+
+          attrs = {
+            ATTR_FLAG_KEY => flag_key,
+            ATTR_VARIANT => variant.to_s,
+            ATTR_REASON => reason_downcase,
+          }
+
+          if allocation_key && !allocation_key.empty? && !exclude_allocation_key?(reason_downcase)
+            attrs[ATTR_ALLOCATION_KEY] = allocation_key
+          end
+
+          if error_code
+            attrs[ATTR_ERROR_TYPE] = normalize_error_type(error_code)
+          end
+
+          attrs
+        end
+
+        def normalize_reason(reason)
+          reason = reason.to_s
+          reason.empty? ? "unknown" : reason.downcase
+        end
+
+        def normalize_error_type(error_code)
+          ERROR_TYPE_MAP.fetch(error_code.to_s, DEFAULT_ERROR_TYPE)
+        end
+
+        def exclude_allocation_key?(reason_downcase)
+          EXCLUDE_ALLOCATION_KEY_REASONS.include?(reason_downcase)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/open_feature/native_evaluator.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
-require_relative '../core/feature_flags'
+require_relative "../core/feature_flags"
+require_relative "ext"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
     # This class is an interface of evaluation logic using native extension
     class NativeEvaluator
+      INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE = "flag configuration is invalid or unsupported"
+
       # NOTE: In a currect implementation configuration is expected to be a raw
       #       JSON string containing feature flags (straight from the remote config)
       #       in the format expected by `libdatadog` without any modifications
@@ -27,12 +31,30 @@ module Datadog
       def get_assignment(flag_key, default_value:, expected_type:, context:)
         result = @configuration.get_assignment(flag_key, expected_type, context)
 
+        return invalid_flag_configuration_error(default_value) if invalid_flag_configuration?(result)
+
         # NOTE: This is a special case when we need to fallback to the default
         #       value, even tho the evaluation itself doesn't produce an error
         #       resolution details
         result.value = default_value if result.variant.nil?
         result
       end
+
+      private
+
+      def invalid_flag_configuration?(result)
+        result.reason == Ext::DEFAULT &&
+          result.error_code.nil? &&
+          result.error_message == INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE
+      end
+
+      def invalid_flag_configuration_error(default_value)
+        ResolutionDetails.build_error(
+          value: default_value,
+          error_code: Ext::PARSE_ERROR,
+          error_message: INVALID_FLAG_CONFIGURATION_ERROR_MESSAGE
+        )
+      end
     end
   end
 end

data/lib/datadog/open_feature/noop_evaluator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require_relative 'resolution_details'
+require_relative "ext"
+require_relative "resolution_details"
 
 module Datadog
   module OpenFeature
@@ -17,7 +17,7 @@ module Datadog
           log?: false,
           error?: true,
           error_code: Ext::PROVIDER_NOT_READY,
-          error_message: 'Waiting for flags configuration',
+          error_message: "Waiting for flags configuration",
           reason: Ext::ERROR
         )
       end