datadog 2.36.0 → 2.40.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

@@ -5,28 +5,28 @@ module Datadog
     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'
+        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'
+        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'
+        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,
+          "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
@@ -40,7 +40,7 @@ module Datadog
           @mutex = Mutex.new
 
           unless @enabled
-            @logger.debug { 'OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled' }
+            @logger.debug { "OpenFeature: OTel metrics not enabled (DD_METRICS_OTEL_ENABLED=false), flag evaluation metrics disabled" }
           end
         end
 
@@ -60,7 +60,7 @@ module Datadog
           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')
+          @telemetry.report(e, description: "OpenFeature: Failed to record evaluation metric")
         end
 
         private
@@ -92,9 +92,9 @@ module Datadog
           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'
+          @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
@@ -133,7 +133,7 @@ module Datadog
 
         def normalize_reason(reason)
           reason = reason.to_s
-          reason.empty? ? 'unknown' : reason.downcase
+          reason.empty? ? "unknown" : reason.downcase
         end
 
         def normalize_error_type(error_code)

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

data/lib/datadog/open_feature/provider.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require 'open_feature/sdk'
+require_relative "ext"
+require_relative "../core/utils/time"
+require "open_feature/sdk"
 
 module Datadog
   module OpenFeature
     # OpenFeature feature flagging provider backed by Datadog Remote Configuration.
     #
-    # Requires openfeature-sdk >= 0.5.1 for flag evaluation metrics support.
+    # Requires openfeature-sdk >= 0.5.1 for flag evaluation metrics and EVP hook support.
+    #
+    # Hook lifecycle note: FlagEvalEVPHook is returned from #hooks so EVP uses the SDK-final
+    # EvaluationDetails. This matches FlagEvalMetricsHook and records defaults/errors produced
+    # by OpenFeature hook failures or post-provider type validation.
     #
     # Implementation follows the OpenFeature contract of Provider SDK.
     # For details see:
@@ -53,7 +58,7 @@ module Datadog
     #   # => 'Welcome back!'
     #   ```
     class Provider
-      NAME = 'Datadog Feature Flagging Provider'
+      NAME = "Datadog Feature Flagging Provider"
 
       attr_reader :metadata
 
@@ -70,8 +75,11 @@ module Datadog
       end
 
       def hooks
-        hook = Datadog.send(:components).open_feature&.flag_eval_hook
-        [hook].compact
+        component = Datadog.send(:components).open_feature
+        [
+          component&.flag_eval_metrics_hook,
+          component&.flag_eval_evp_hook,
+        ].compact
       end
 
       def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
@@ -101,57 +109,116 @@ module Datadog
       private
 
       def evaluate(flag_key, default_value:, expected_type:, evaluation_context:)
+        # Stamp evaluation entry time once, here on the eval thread. The EVP path uses this for
+        # accurate first/last_evaluation bounds instead of a later hook-fire clock read.
+        eval_time_ms = (Core::Utils::Time.now.to_f * 1000).to_i
+
         engine = OpenFeature.engine
-        return component_not_configured_default(default_value) if engine.nil?
+        return component_not_configured_default(default_value, eval_time_ms) if engine.nil?
+
+        result = fetch_engine_value(engine, flag_key, default_value, expected_type, evaluation_context)
 
-        result = engine.fetch_value(
+        # Build metadata before branching so provider-returned details carry eval-entry time.
+        flag_meta = build_flag_metadata(result, eval_time_ms)
+
+        if result.error?
+          return sdk_error_details(default_value, result.error_code, result.error_message, result.reason, flag_meta)
+        end
+
+        # Drive APM span enrichment directly from the evaluation path. This is the only reliable
+        # way to attach `ffe_*` tags across all supported OpenFeature SDK versions, since older
+        # SDKs do not dispatch provider hooks. Guarded so enrichment can never break evaluation.
+        enrich_span(flag_key, result, evaluation_context)
+
+        sdk_success_details(result, flag_meta)
+      rescue => e
+        error_message = "#{e.class}: #{e.message}"
+        error_result = Datadog::OpenFeature::ResolutionDetails.build_error(
+          value: default_value,
+          error_code: Ext::GENERAL,
+          error_message: error_message
+        )
+        error_flag_meta = build_flag_metadata(error_result, eval_time_ms || (Core::Utils::Time.now.to_f * 1000).to_i)
+
+        sdk_error_details(default_value, Ext::GENERAL, error_message, Ext::ERROR, error_flag_meta)
+      end
+
+      def fetch_engine_value(engine, flag_key, default_value, expected_type, evaluation_context)
+        engine.fetch_value(
           flag_key,
           default_value: default_value,
           expected_type: expected_type,
           evaluation_context: evaluation_context
         )
+      end
 
-        if result.error?
-          return ::OpenFeature::SDK::Provider::ResolutionDetails.new(
-            value: default_value,
-            error_code: result.error_code,
-            error_message: result.error_message,
-            reason: result.reason
-          )
-        end
-
+      def sdk_success_details(result, flag_meta)
         ::OpenFeature::SDK::Provider::ResolutionDetails.new(
           value: result.value,
           variant: result.variant,
           reason: result.reason,
-          flag_metadata: build_flag_metadata(result),
+          flag_metadata: flag_meta,
         )
-      rescue => e
+      end
+
+      def sdk_error_details(default_value, error_code, error_message, reason, flag_meta = {})
         ::OpenFeature::SDK::Provider::ResolutionDetails.new(
           value: default_value,
-          error_code: Ext::GENERAL,
-          error_message: "#{e.class}: #{e.message}",
-          reason: Ext::ERROR
+          error_code: error_code,
+          error_message: error_message,
+          reason: reason,
+          flag_metadata: flag_meta
         )
       end
 
-      def build_flag_metadata(result)
-        metadata = result.flag_metadata || {}
+      def build_flag_metadata(result, eval_time_ms)
+        metadata = result.flag_metadata&.dup || {}
         allocation_key = result.allocation_key
-        if allocation_key && !allocation_key.empty?
-          metadata = metadata.dup
-          metadata['__dd_allocation_key'] = allocation_key
-        end
+        metadata[Ext::METADATA_ALLOCATION_KEY] = allocation_key if allocation_key && !allocation_key.empty?
+
+        # Eval-time stamped at provider entry; the EVP hook reads 'dd.eval.timestamp_ms' for
+        # accurate first/last_evaluation bounds (it falls back to hook-fire time when absent).
+        metadata["dd.eval.timestamp_ms"] = eval_time_ms
 
         metadata
       end
 
-      def component_not_configured_default(value)
+      # Dispatch span enrichment from the evaluation path in a never-throw
+      # wrapper. Reads the split serial id / do-log flag directly off the Datadog
+      # `ResolutionDetails` struct and the targeting key off the built evaluation
+      # context. A nil hook (gate off or component absent) is a no-op.
+      def enrich_span(flag_key, result, evaluation_context)
+        hook = span_enrichment_hook
+        return unless hook
+
+        # Hook resolved first so the common gate-off path short-circuits without
+        # resolving the tracer. With the gate on but no active trace there is
+        # nowhere to attach tags, so skip before building the capture call.
+        return unless Datadog::Tracing.active_trace
+
+        hook.capture(
+          flag_key: flag_key,
+          variant: result.variant,
+          value: result.value,
+          serial_id: result.serial_id,
+          do_log: result.log? || false,
+          targeting_key: evaluation_context&.targeting_key,
+        )
+      rescue => e
+        Datadog.logger.debug { "OpenFeature: span enrichment dispatch failed: #{e.class}: #{e.message}" }
+      end
+
+      def span_enrichment_hook
+        Datadog.send(:components).open_feature&.span_enrichment_hook
+      end
+
+      def component_not_configured_default(value, eval_time_ms)
         ::OpenFeature::SDK::Provider::ResolutionDetails.new(
           value: value,
           error_code: Ext::PROVIDER_FATAL,
           error_message: "Datadog's OpenFeature component must be configured",
-          reason: Ext::ERROR
+          reason: Ext::ERROR,
+          flag_metadata: {"dd.eval.timestamp_ms" => eval_time_ms}
         )
       end
     end