feat: implement DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT behavior

Adds three behaviors at the single extraction chokepoint
(ddtrace_apply_distributed_tracing_result):

- continue (default): inherit upstream trace context unchanged
- restart: start a fresh trace; upstream captured as a span link with
  reason=propagation_behavior_extract. When the root span doesn't exist
  yet at request-init time, the link is queued in
  DDTRACE_G(pending_upstream_span_link) and attached in ddtrace_open_span.
- ignore: drop all extracted context including baggage and sampling priority

Also extracts ddtrace_build_span_link_from_result() from the SpanLink
fromHeaders method so it can be reused by the restart path.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: MilanGarnier

tracer/ddtrace.c

@@ -436,6 +436,7 @@ static void dd_initialize_request(void) {
     DDTRACE_G(default_priority_sampling) = DDTRACE_PRIORITY_SAMPLING_UNKNOWN;
     DDTRACE_G(propagated_priority_sampling) = DDTRACE_PRIORITY_SAMPLING_UNSET;
     DDTRACE_G(inferred_span_created) = false;
+    ZVAL_NULL(&DDTRACE_G(pending_upstream_span_link));
     zend_hash_init(&DDTRACE_G(root_span_tags_preset), 8, unused, ZVAL_PTR_DTOR, 0);
     zend_hash_init(&DDTRACE_G(propagated_root_span_tags), 8, unused, ZVAL_PTR_DTOR, 0);
     zend_hash_init(&DDTRACE_G(tracestate_unknown_dd_keys), 8, unused, ZVAL_PTR_DTOR, 0);
@@ -527,6 +528,8 @@ static void dd_clean_globals(void) {
     zend_hash_destroy(&DDTRACE_G(tracestate_unknown_dd_keys));
     zend_hash_destroy(&DDTRACE_G(propagated_root_span_tags));
     zend_hash_destroy(&DDTRACE_G(baggage));
+    zval_ptr_dtor(&DDTRACE_G(pending_upstream_span_link));
+    ZVAL_NULL(&DDTRACE_G(pending_upstream_span_link));
 
     if (DDTRACE_G(curl_multi_injecting_spans)) {
         if (GC_DELREF(DDTRACE_G(curl_multi_injecting_spans)) == 0) {

tracer/ddtrace_globals.h

@@ -89,6 +89,7 @@ typedef struct {
     zend_object *git_object;
 
     bool inferred_span_created;
+    zval pending_upstream_span_link; // span link queued by PROPAGATION_BEHAVIOR_EXTRACT=restart; consumed on root span open
 
     HashTable resource_weak_storage;
     dtor_func_t resource_dtor_func;

tracer/distributed_tracing_headers.c

@@ -617,6 +617,59 @@ void apply_baggage_span_tags(zend_string *key, zval *val, zend_array *meta) {
 void ddtrace_apply_distributed_tracing_result(ddtrace_distributed_tracing_result *result, ddtrace_root_span_data *span) {
     zval zv;
 
+    int behavior = get_DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT();
+
+    if (behavior == DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT_IGNORE) {
+        // behavior=ignore: drop all extracted context including baggage
+        zend_hash_destroy(&result->propagated_tags);
+        zend_hash_destroy(&result->meta_tags);
+        zend_hash_destroy(&result->tracestate_unknown_dd_keys);
+        zend_hash_destroy(&result->baggage);
+        if (result->origin) { zend_string_release(result->origin); }
+        if (result->tracestate) { zend_string_release(result->tracestate); }
+        return;
+    }
+
+    if (behavior == DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT_RESTART && (result->trace_id.low || result->trace_id.high)) {
+        // behavior=restart: zero trace_id so a fresh trace starts; upstream captured as span link
+        // drop _dd.p.* first so the builder does not include them in link attributes
+        zend_string *mk;
+        zend_string *to_delete[64];
+        int to_delete_count = 0;
+        ZEND_HASH_FOREACH_STR_KEY(&result->meta_tags, mk) {
+            if (mk && ZSTR_LEN(mk) > 6 && strncmp(ZSTR_VAL(mk), "_dd.p.", 6) == 0) {
+                to_delete[to_delete_count++] = mk;
+            }
+        } ZEND_HASH_FOREACH_END();
+        for (int i = 0; i < to_delete_count; i++) {
+            zend_hash_del(&result->meta_tags, to_delete[i]);
+        }
+        zend_hash_clean(&result->propagated_tags);
+
+        zval link_zv;
+        object_init_ex(&link_zv, ddtrace_ce_span_link);
+        ddtrace_span_link *link = (ddtrace_span_link *)Z_OBJ(link_zv);
+        ddtrace_build_span_link_from_result(result, link);
+
+        zval reason_val;
+        ZVAL_STR(&reason_val, zend_string_init(ZEND_STRL("reason"), 0));
+        zval reason_str;
+        ZVAL_STR(&reason_str, zend_string_init(ZEND_STRL("propagation_behavior_extract"), 0));
+        zend_hash_update(Z_ARR(link->property_attributes), Z_STR(reason_val), &reason_str);
+        zval_ptr_dtor(&reason_val);
+
+        result->trace_id = (datadog_trace_id){0};
+        result->parent_id = 0;
+
+        if (span) {
+            zend_array *links = ddtrace_property_array(&span->property_links);
+            zend_hash_next_index_insert(links, &link_zv);
+        } else {
+            zval_ptr_dtor(&DDTRACE_G(pending_upstream_span_link));
+            ZVAL_COPY_VALUE(&DDTRACE_G(pending_upstream_span_link), &link_zv);
+        }
+    }
+
     zend_array *root_meta = span ? ddtrace_property_array(&span->property_meta) : &DDTRACE_G(root_span_tags_preset);
     if (span) {
         zend_string *tagname;

tracer/distributed_tracing_headers.h

@@ -2,6 +2,7 @@
 #define DD_DISTRIBUTED_TRACING_HEADERS_H
 
 #include "ddtrace.h"
+#include "span.h"
 #include "priority_sampling/priority_sampling.h"
 #include <zai_string/string.h>
 
@@ -24,5 +25,6 @@ ddtrace_distributed_tracing_result ddtrace_read_distributed_tracing_ids(ddtrace_
 void ddtrace_apply_distributed_tracing_result(ddtrace_distributed_tracing_result *result, ddtrace_root_span_data *span);
 bool ddtrace_read_zai_header(zai_str zai_header, const char *lowercase_header, zend_string **header_value, void *data);
 bool ddtrace_read_array_header(zai_str zai_header, const char *lowercase_header, zend_string **header_value, void *data);
+void ddtrace_build_span_link_from_result(ddtrace_distributed_tracing_result *result, ddtrace_span_link *link);
 
 #endif // DD_DISTRIBUTED_TRACING_HEADERS_H

tracer/functions.c

@@ -231,6 +231,22 @@ PHP_METHOD(DDTrace_SpanLink, jsonSerialize) {
     RETURN_ARR(array);
 }
 
+void ddtrace_build_span_link_from_result(ddtrace_distributed_tracing_result *result, ddtrace_span_link *link) {
+    ZVAL_STR(&link->property_trace_id, datadog_trace_id_as_hex_string(result->trace_id));
+    ZVAL_STR(&link->property_span_id, ddtrace_span_id_as_hex_string(result->parent_id));
+    array_init(&link->property_attributes);
+    zend_hash_copy(Z_ARR(link->property_attributes), &result->meta_tags, NULL);
+
+    zend_string *propagated_tags = ddtrace_format_propagated_tags(&result->propagated_tags, &result->meta_tags);
+    zend_string *full_tracestate = ddtrace_format_tracestate(result->tracestate, 0, result->origin, result->priority_sampling, propagated_tags, &result->tracestate_unknown_dd_keys);
+    if (propagated_tags) {
+        zend_string_release(propagated_tags);
+    }
+    if (full_tracestate) {
+        ZVAL_STR(&link->property_trace_state, full_tracestate);
+    }
+}
+
 static ddtrace_distributed_tracing_result dd_parse_distributed_tracing_headers_function(INTERNAL_FUNCTION_PARAMETERS, bool *success);
 ZEND_METHOD(DDTrace_SpanLink, fromHeaders) {
     bool success;
@@ -245,19 +261,7 @@ ZEND_METHOD(DDTrace_SpanLink, fromHeaders) {
         return;
     }
 
-    ZVAL_STR(&link->property_trace_id, datadog_trace_id_as_hex_string(result.trace_id));
-    ZVAL_STR(&link->property_span_id, ddtrace_span_id_as_hex_string(result.parent_id));
-    array_init(&link->property_attributes);
-    zend_hash_copy(Z_ARR(link->property_attributes), &result.meta_tags, NULL);
-
-    zend_string *propagated_tags = ddtrace_format_propagated_tags(&result.propagated_tags, &result.meta_tags);
-    zend_string *full_tracestate = ddtrace_format_tracestate(result.tracestate, 0, result.origin, result.priority_sampling, propagated_tags, &result.tracestate_unknown_dd_keys);
-    if (propagated_tags) {
-        zend_string_release(propagated_tags);
-    }
-    if (full_tracestate) {
-        ZVAL_STR(&link->property_trace_state, full_tracestate);
-    }
+    ddtrace_build_span_link_from_result(&result, link);
 
     result.meta_tags.pDestructor = NULL; // we moved values directly
     zend_hash_destroy(&result.meta_tags);

tracer/span.c

@@ -296,6 +296,13 @@ ddtrace_span_data *ddtrace_open_span(enum ddtrace_span_dataype type) {
         span->parent = NULL;
 
         ddtrace_set_root_span_properties(root);
+
+        if (primary_stack && Z_TYPE(DDTRACE_G(pending_upstream_span_link)) == IS_OBJECT) {
+            // attach upstream link queued by PROPAGATION_BEHAVIOR_EXTRACT=restart
+            zend_array *links = ddtrace_property_array(&span->property_links);
+            zend_hash_next_index_insert(links, &DDTRACE_G(pending_upstream_span_link));
+            ZVAL_NULL(&DDTRACE_G(pending_upstream_span_link));
+        }
     } else {
         ++parent_span->active_child_spans;