datadog 2.38.0 → 2.39.0

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,14 +1,14 @@
 # frozen_string_literal: true
 
-require_relative '../core/feature_flags'
-require_relative 'ext'
-require_relative 'resolution_details'
+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'
+      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)

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,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
-require_relative '../core/utils/time'
-require 'open_feature/sdk'
+require_relative "ext"
+require_relative "../core/utils/time"
+require "open_feature/sdk"
 
 module Datadog
   module OpenFeature
@@ -58,7 +58,7 @@ module Datadog
     #   # => 'Welcome back!'
     #   ```
     class Provider
-      NAME = 'Datadog Feature Flagging Provider'
+      NAME = "Datadog Feature Flagging Provider"
 
       attr_reader :metadata
 
@@ -76,9 +76,10 @@ module Datadog
 
       def hooks
         component = Datadog.send(:components).open_feature
-        otel_hook = component&.flag_eval_metrics_hook
-        evp_hook = component&.flag_eval_evp_hook
-        [otel_hook, evp_hook].compact
+        [
+          component&.flag_eval_metrics_hook,
+          component&.flag_eval_evp_hook,
+        ].compact
       end
 
       def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
@@ -124,6 +125,11 @@ module Datadog
           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}"
@@ -168,22 +174,51 @@ module Datadog
       def build_flag_metadata(result, eval_time_ms)
         metadata = result.flag_metadata&.dup || {}
         allocation_key = result.allocation_key
-        metadata['__dd_allocation_key'] = allocation_key if allocation_key && !allocation_key.empty?
+        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["dd.eval.timestamp_ms"] = eval_time_ms
 
         metadata
       end
 
+      # 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,
-          flag_metadata: {'dd.eval.timestamp_ms' => eval_time_ms}
+          flag_metadata: {"dd.eval.timestamp_ms" => eval_time_ms}
         )
       end
     end

data/lib/datadog/open_feature/remote.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../core/remote/dispatcher'
+require_relative "../core/remote/dispatcher"
 
 module Datadog
   module OpenFeature
@@ -8,7 +8,7 @@ module Datadog
     module Remote
       class << self
         FFE_FLAG_CONFIGURATION_RULES = 1 << 46
-        FFE_PRODUCTS = ['FFE_FLAGS'].freeze
+        FFE_PRODUCTS = ["FFE_FLAGS"].freeze
         FFE_CAPABILITIES = [FFE_FLAG_CONFIGURATION_RULES].freeze
 
         def capabilities

data/lib/datadog/open_feature/resolution_details.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'ext'
+require_relative "ext"
 
 module Datadog
   module OpenFeature
@@ -15,6 +15,7 @@ module Datadog
       :error_message,
       :flag_metadata,
       :allocation_key,
+      :serial_id,
       :extra_logging,
       :log?,
       :error?,
@@ -27,7 +28,8 @@ module Datadog
           error_message: error_message,
           reason: reason,
           error?: true,
-          log?: false
+          log?: false,
+          serial_id: nil
         ).freeze
       end
     end

data/lib/datadog/open_feature/transport.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative '../core/encoding'
-require_relative '../core/evp'
-require_relative '../core/transport/http'
-require_relative '../core/transport/http/env'
-require_relative '../core/transport/http/api/endpoint'
-require_relative '../core/transport/http/api/instance'
-require_relative '../core/transport/parcel'
-require_relative '../core/transport/request'
+require_relative "../core/encoding"
+require_relative "../core/evp"
+require_relative "../core/transport/http"
+require_relative "../core/transport/http/env"
+require_relative "../core/transport/http/api/endpoint"
+require_relative "../core/transport/http/api/instance"
+require_relative "../core/transport/parcel"
+require_relative "../core/transport/request"
 
 module Datadog
   module OpenFeature
@@ -17,14 +17,14 @@ module Datadog
         class Spec
           def initialize
             @endpoint = Core::Transport::HTTP::API::Endpoint.new(
-              :post, '/evp_proxy/v2/api/v2/exposures'
+              :post, "/evp_proxy/v2/api/v2/exposures"
             )
           end
 
           # TODO rename to send_request?
           def call(env, &block)
             @endpoint.call(env) do |request_env|
-              request_env.headers['Content-Type'] = env.request.parcel.content_type
+              request_env.headers["Content-Type"] = env.request.parcel.content_type
               request_env.headers[Core::EVP::SUBDOMAIN_HEADER_NAME] =
                 Core::EVP::EVENT_PLATFORM_INTAKE_SUBDOMAIN
               request_env.body = env.request.parcel.data
@@ -40,13 +40,13 @@ module Datadog
         class FlagevaluationsSpec
           def initialize
             @endpoint = Core::Transport::HTTP::API::Endpoint.new(
-              :post, '/evp_proxy/v2/api/v2/flagevaluation'
+              :post, "/evp_proxy/v2/api/v2/flagevaluation"
             )
           end
 
           def call(env, &block)
             @endpoint.call(env) do |request_env|
-              request_env.headers['Content-Type'] = env.request.parcel.content_type
+              request_env.headers["Content-Type"] = env.request.parcel.content_type
               request_env.headers[Core::EVP::SUBDOMAIN_HEADER_NAME] =
                 Core::EVP::EVENT_PLATFORM_INTAKE_SUBDOMAIN
               request_env.body = env.request.parcel.data
@@ -60,7 +60,7 @@ module Datadog
           Core::Transport::HTTP.build(
             agent_settings: agent_settings,
             logger: logger
-          ) { |t| t.api('exposures', HTTP::Spec.new) }.to_transport(self)
+          ) { |t| t.api("exposures", HTTP::Spec.new) }.to_transport(self)
         end
 
         # Build a transport instance for the flagevaluation EVP endpoint.
@@ -68,7 +68,7 @@ module Datadog
           Core::Transport::HTTP.build(
             agent_settings: agent_settings,
             logger: logger
-          ) { |t| t.api('flagevaluations', HTTP::FlagevaluationsSpec.new) }.to_transport(self)
+          ) { |t| t.api("flagevaluations", HTTP::FlagevaluationsSpec.new) }.to_transport(self)
         end
 
         def initialize(apis, default_api, logger:)

data/lib/datadog/open_feature.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'core/configuration'
-require_relative 'open_feature/configuration'
+require_relative "core/configuration"
+require_relative "open_feature/configuration"
 
 module Datadog
   # A namespace for the OpenFeature component.

data/lib/datadog/opentelemetry/api/baggage.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'trace/span'
-require_relative '../../tracing/trace_operation'
-require_relative '../trace'
+require_relative "trace/span"
+require_relative "../../tracing/trace_operation"
+require_relative "../trace"
 
 module Datadog
   module OpenTelemetry

data/lib/datadog/opentelemetry/api/context.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'trace/span'
-require_relative '../../tracing/trace_operation'
-require_relative '../trace'
+require_relative "trace/span"
+require_relative "../../tracing/trace_operation"
+require_relative "../trace"
 
 module Datadog
   module OpenTelemetry
@@ -143,7 +143,7 @@ module Datadog
             unless calls_matched
               ::OpenTelemetry.handle_error(
                 exception: ::OpenTelemetry::Context::DetachError.new(
-                  'calls to detach should match corresponding calls to attach.'
+                  "calls to detach should match corresponding calls to attach."
                 )
               )
             end