feat(FeatureFlags): FFE APM feature-flag span enrichment (experimental, gated)

components-rs/common.h

@@ -484,6 +484,8 @@ typedef struct ddog_FfeResult {
   _zend_string * allocation_key;
   int32_t reason;
   int32_t error_code;
+  int32_t serial_id;
+  bool has_serial_id;
   bool do_log;
   bool valid;
 } ddog_FfeResult;

components-rs/ffe.rs

@@ -97,6 +97,14 @@ pub struct FfeResult {
     pub allocation_key: MaybeOwnedZendString,
     pub reason: i32,
     pub error_code: i32,
+    // serial_id is the selected split's serial id, carried for APM span
+    // enrichment (ffe_flags_enc). The source field is Option<i32>; since the
+    // C ABI cannot represent Option<i32> as a plain field, we surface the
+    // presence separately via has_serial_id. Consumers MUST gate on
+    // has_serial_id (the Pattern B "missing variant => default" semantic) and
+    // never treat serial_id == 0 as "absent".
+    pub serial_id: i32,
+    pub has_serial_id: bool,
     pub do_log: bool,
     pub valid: bool,
 }
@@ -220,6 +228,8 @@ fn result_from_assignment(assignment: Result<ffe::Assignment, EvaluationError>)
                     AssignmentReason::Default => REASON_DEFAULT,
                 },
                 error_code: ERROR_NONE,
+                serial_id: assignment.serial_id.unwrap_or(0),
+                has_serial_id: assignment.serial_id.is_some(),
                 do_log: assignment.do_log,
                 valid: true,
             }
@@ -244,6 +254,8 @@ fn result_from_assignment(assignment: Result<ffe::Assignment, EvaluationError>)
                 allocation_key: None,
                 reason,
                 error_code,
+                serial_id: 0,
+                has_serial_id: false,
                 do_log: false,
                 valid: true,
             }
@@ -258,6 +270,8 @@ fn invalid_result() -> FfeResult {
         allocation_key: None,
         reason: REASON_ERROR,
         error_code: ERROR_GENERAL,
+        serial_id: 0,
+        has_serial_id: false,
         do_log: false,
         valid: false,
     }

ext/configuration.h

@@ -109,7 +109,8 @@ enum datadog_sidecar_connection_mode {
     CONFIG(DOUBLE, DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS, "5.0", .ini_change = zai_config_system_ini_change)  \
     CONFIG(BOOL, DD_REMOTE_CONFIG_ENABLED, "true", .ini_change = zai_config_system_ini_change)                 \
     CONFIG(INT, DD_TRACE_RETRY_INTERVAL, "100", .ini_change = zai_config_system_ini_change)                    \
-    CONFIG(BOOL, DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED, "true")
+    CONFIG(BOOL, DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED, "true")                                       \
+    CONFIG(BOOL, DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED, "false")
 
 #define DD_CONFIGURATIONS_ONLY
 #ifdef DDTRACE

metadata/supported-configurations.json

@@ -403,6 +403,13 @@
         "default": "false"
       }
     ],
+    "DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "false"
+      }
+    ],
     "DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED": [
       {
         "implementation": "B",

src/DDTrace/OpenFeature/DataDogProvider.php

@@ -111,12 +111,15 @@ private function resolve(
         mixed $defaultValue,
         ?EvaluationContext $context
     ): ResolutionDetailsInterface {
-        $details = $this->evaluate($flagKey, $expectedType, $defaultValue, $this->normalizeContext($context));
+        $normalizedContext = $this->normalizeContext($context);
+        $details = $this->evaluate($flagKey, $expectedType, $defaultValue, $normalizedContext);
         $this->warnIfNonProductionRuntime($details);
         // The PHP OpenFeature SDK does not pass ResolutionDetails to finally
         // hooks, so PHP records metrics here after native evaluation has the
         // final provider result.
         $this->recordEvaluationMetric($flagKey, $details);
+        // APM span enrichment is recorded inside NativeEvaluator::evaluate()
+        // (the shared choke point), so there is nothing to do here.
 
         $builder = (new ResolutionDetailsBuilder())
             ->withValue($details->getValue())

src/api/FeatureFlags/Internal/NativeEvaluator.php

@@ -3,6 +3,7 @@
 namespace DDTrace\FeatureFlags\Internal;
 
 use DDTrace\FeatureFlags\EvaluationType;
+use DDTrace\FeatureFlags\SpanEnrichmentRegistry;
 
 final class NativeEvaluator implements Evaluator
 {
@@ -50,7 +51,17 @@ public function evaluate(
             $rawResult = $this->withProviderState($rawResult);
         }
 
-        return $this->mapper->map($rawResult, $expectedType, $defaultValue);
+        $details = $this->mapper->map($rawResult, $expectedType, $defaultValue);
+
+        // APM feature-flag span enrichment. This is the single choke point both
+        // the native Client and the OpenFeature DataDogProvider evaluate through,
+        // and it is only reachable with the extension loaded (UnavailableEvaluator
+        // is returned otherwise), so enrichment is recorded here once rather than
+        // duplicated in each caller. No-op when the gate is off or there is no
+        // active root span; never throws into evaluation.
+        SpanEnrichmentRegistry::record($flagKey, $details, $targetingKey);
+
+        return $details;
     }
 
     private function typeId($expectedType)

src/api/FeatureFlags/Internal/ResultMapper.php

@@ -274,6 +274,19 @@ private function exposureData($rawResult)
             $exposureData['doLog'] = (bool) $this->read($rawResult, array('do_log', 'doLog'), false);
         }
 
+        // serialId is the selected split's serial id, surfaced from the native
+        // bridge for APM span enrichment. It is only present when the native
+        // result actually carried one; a null/absent value must be left out
+        // entirely rather than defaulted to 0/false. Absence alone does NOT
+        // mean a runtime default was used -- a waterfall-assigned variant can
+        // also have no serial id. SpanEnrichmentRegistry::record() only
+        // treats an evaluation as a runtime default when BOTH serialId AND the
+        // variant are absent.
+        $serialId = $this->read($rawResult, array('serial_id', 'serialId'), null);
+        if ($serialId !== null) {
+            $exposureData['serialId'] = (int) $serialId;
+        }
+
         return $exposureData;
     }