feat(tracer): align C span code with v1-compatible stub API (v2 groundwork) by Leiyks · Pull Request #4046 · DataDog/dd-trace-php

Leiyks · 2026-07-17T12:51:40Z

What & why

Part of APMLP-1197 (dd-trace-php v1/v2 roadmap). The v1-compatible span
stub API (tracer/ddtrace.stub.php) landed earlier on this branch; this
brings the tracer C code into consistency with it. The v04 wire
format is intentionally kept byte-identical — libdatadog's v1 span
FFI is not yet available, so no wire/protocol switch happens here.

Changes

arginfo + struct offsets: regenerated ddtrace_arginfo.h; reordered
ddtrace_span_properties / ddtrace_root_span_data / ddtrace_span_stack in
span.h to match the new stub property order (offset parity is
ABI-critical — a mismatch is silent data corruption).
SpanEvent/SpanLink: dropped JsonSerializable + jsonSerialize();
relocated the serialization into serializer.c → _dd.span_links / events
meta blobs are byte-identical.
component/spanKind: now sourced from the new SpanData properties and
translated back to meta (component / span.kind) at serialize time, so
the wire is unchanged; new SpanKind class registered.
Dead code: removed stub-removed functions + DD_TRACE_WARN_LEGACY_DD_TRACE;
finished the userland integration-analytics removal (Integration.php +
call sites); deleted orphaned tests and rewrote dd_trace_reset helper
tests without weakening coverage.

Deliberate scope decisions

Wire stays v04 (no native ddog_span_new_link/event switch) — deferred
until libdatadog v1 FFI is ready.
New properties attributes / samplingMechanism / hostname get struct
slots (to keep offsets correct) but are left unwired for now.
ddtrace_arginfo.h keeps deprecations doc-only (hand-stripped the
ZEND_ACC_DEPRECATED flags current gen_stub now emits) to match the
committed convention and avoid runtime E_DEPRECATED on hot paths;
reconciling gen_stub output is a separate follow-up.

Testing

Container build clean; 22 span-shape + 26 curl integration + 30
ConfigurationTest tests passing; links/events wire proven byte-identical.

Draft: pending full CI.

Relationship to the V1 Efficient Trace Payload protocol

This change aligns the userland span API and tracer C with the approved Efficient Trace Payload Protocol RFC and the WIP Tracer Implementation Guide for V1 Trace Payloads, without changing the wire format. The v04 payload remains byte-for-byte the sender's output because the vendored libdatadog exposes the v1 types (libdd-trace-utils/src/span/v1/mod.rs, pb.idx.rs) only internally — the PHP FFI (components-rs/bytes.rs) still binds ddog_SpanBytes = v04::SpanBytes, so there is no v1 serializer to drive yet.

Implemented now (v1-shaped API, v04 wire):

Promoted span fields env, version, component, kind exist as SpanData properties (RFC idx.Span fields 13–16). Internal C producers set the property; the serializer translates component/spanKind back into meta["component"]/meta["span.kind"] so v04 is unchanged.
DDTrace\SpanKind constants match the OTEL SpanKind enum exactly (RFC field 16: kind = otel.SpanKind): UNSPECIFIED=0, INTERNAL=1, SERVER=2, CLIENT=3, PRODUCER=4, CONSUMER=5.

Deferred until the v1 FFI lands (groundwork present, unwired):

Config gate & negotiation (guide "Enablement"): enable only when DD_TRACE_AGENT_PROTOCOL_VERSION ∈ {"1.0","1"} and the agent /info advertises /v1.0/traces, with mandatory fallback to v04 when absent. Intentionally not added yet to avoid a no-op config key with no serializer behind it.
AnyValue attributes (RFC idx.AnyValue): SpanData::$attributes / SpanStack::$attributes reserved; the initial implementation will use String/Float/Bytes and fold meta/metrics/meta_struct into a single typed map (guide L14–16).
Chunk-level promotions: 128-bit big-endian traceID bytes (RFC idx.TraceChunk field 6 / guide L33) and samplingMechanism as a bare uint32 replacing _dd.p.dm:-N (RFC field 7 / guide L36) — RootSpanData::$samplingMechanism reserved.
hostname promoted to the TracerPayload (RFC field 8) — RootSpanData::$hostname reserved; v04 keeps emitting _dd.hostname.
error as bool (RFC idx.Span field 8) and 429 / Datadog-Send-Real-Http-Status back-off (guide L21–24) — trace sender untouched.

Note for the v1 serializer work: the promoted fields have a split source of truth (property for C producers, meta for userland integrations such as OTel SpanBuilder and Kafka). The v1 serializer must read each promoted value from property-or-meta and remove it from the attributes map, otherwise a v1 payload would carry the value both in the promoted field and in attributes (guide L19).

V1 protocol now enabled (behind a flag)

With libdatadog's v1 encoder (#2145) + sidecar transport (#2156) available, this branch now emits the V1 Efficient Trace Payload end-to-end on the sidecar path, gated by DD_TRACE_AGENT_PROTOCOL_VERSION and negotiated via agent /info:

DD_TRACE_AGENT_PROTOCOL_VERSION=1.0 AND the agent /info advertising /v1.0/traces -> POST /v1.0/traces with v1 msgpack (proto-field-number keys, streaming string table, promoted env/version/component/span.kind, chunk-level trace_id + sampling_mechanism, typed AnyValue attributes, native span_links/span_events).
otherwise (default 0.4, or agent doesn't advertise, or info unknown) -> unchanged POST /v0.4/traces.

Depends on the libdatadog PR adding ddog_send_traces_to_sidecar_v1 (based on #2156). Not yet covered: the in-process (non-sidecar, PHP <=8.2) sender path.

datadog-datadog-prod-us1-2 · 2026-07-17T12:54:52Z

✨ Unblock PR with BitsAI

⚠️ Warnings

🚦 11 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-php | System Tests: [parametric]

🧪 15 Tests failed

tests.parametric.test_otel_span_methods.Test_Otel_Span_Methods.test_otel_span_basic_reserved_attributes_overrides_analytics_event[FALSE-0-library_env0, parametric-php]

from system_tests_suite

AssertionError: assert None == 0
 &#43;  where None = &lt;built-in method get of dict object at 0x7f78a7763d40&gt;(&#39;_dd1.sr.eausr&#39;)
 &#43;    where &lt;built-in method get of dict object at 0x7f78a7763d40&gt; = {&#39;_dd.agent_psr&#39;: 1.0, &#39;_sampling_priority_v1&#39;: 1.0, &#39;process.pid&#39;: 7.0, &#39;process_id&#39;: 7.0}.get

self = &lt;tests.parametric.test_otel_span_methods.Test_Otel_Span_Methods object at 0x7f78a81a06b0&gt;
test_agent = &lt;utils.docker_fixtures._test_agent.TestAgentAPI object at 0x7f78a71966c0&gt;
test_library = &lt;utils.docker_fixtures._test_clients._test_client_parametric.ParametricTestClientApi object at 0x7f78a7566270&gt;

    @pytest.mark.parametrize(
        (&#34;analytics_event_value&#34;, &#34;expected_metric_value&#34;),
...

tests.parametric.test_otel_span_methods.Test_Otel_Span_Methods.test_otel_span_basic_reserved_attributes_overrides_analytics_event[False-00-library_env0, parametric-php]

from system_tests_suite

AssertionError: assert None == 0
 &#43;  where None = &lt;built-in method get of dict object at 0x7f78a7e00f40&gt;(&#39;_dd1.sr.eausr&#39;)
 &#43;    where &lt;built-in method get of dict object at 0x7f78a7e00f40&gt; = {&#39;_dd.agent_psr&#39;: 1.0, &#39;_sampling_priority_v1&#39;: 1.0, &#39;process.pid&#39;: 7.0, &#39;process_id&#39;: 7.0}.get

self = &lt;tests.parametric.test_otel_span_methods.Test_Otel_Span_Methods object at 0x7f78a81a05f0&gt;
test_agent = &lt;utils.docker_fixtures._test_agent.TestAgentAPI object at 0x7f78a71966c0&gt;
test_library = &lt;utils.docker_fixtures._test_clients._test_client_parametric.ParametricTestClientApi object at 0x7f78a6b345c0&gt;

    @pytest.mark.parametrize(
        (&#34;analytics_event_value&#34;, &#34;expected_metric_value&#34;),
...

View all failed tests

DataDog/apm-reliability/dd-trace-php | check-big-regressions

DataDog/apm-reliability/dd-trace-php | test_extension_ci: [7.0]

View all 11 failed jobs.

ℹ️ Info

No other issues found (see more)

❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 60.63% (-0.00%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 84351df | Docs | Datadog PR Page | Give us feedback!}

pr-commenter · 2026-07-17T14:12:52Z

Benchmarks [ tracer ]

Benchmark execution time: 2026-08-06 14:01:49

Comparing candidate commit 84351df in PR branch leiyks/dd-trace-php-v2 with baseline commit 89b12c4 in branch master.

Some scenarios are present only in baseline or only in candidate runs. If you didn't create or remove some scenarios in your branch, this maybe a sign of crashed benchmarks 💥💥💥
Check Gitlab CI job log to find if any benchmark has crashed.

Scenarios present only in baseline:

MessagePackSerializationBench/benchMessagePackSerialization
MessagePackSerializationBench/benchMessagePackSerialization-opcache

Found 2 performance improvements and 17 performance regressions! Performance is the same for 170 metrics, 1 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

scenario:BM_TeaSapiSpindown

🟥 execution_time [+12.000µs; +30.380µs] or [+2.305%; +5.835%]

scenario:ContextPropagationBench/benchExtractHeaders64Bit-opcache

🟩 execution_time [-971.926ns; -896.074ns] or [-45.609%; -42.049%]

scenario:ContextPropagationBench/benchExtractTraceContext128Bit-opcache

🟩 execution_time [-975.495ns; -892.505ns] or [-35.153%; -32.162%]

scenario:ContextPropagationBench/benchInject128Bit-opcache

🟥 execution_time [+833.023ns; +930.977ns] or [+49.703%; +55.548%]

scenario:ContextPropagationBench/benchInject64Bit-opcache

🟥 execution_time [+566.059ns; +941.941ns] or [+2.995%; +4.984%]

scenario:HookBench/benchHookOverheadTraceMethod-opcache

🟥 mem_peak [+64.181KB; +64.186KB] or [+3.008%; +3.008%]

scenario:SamplingRuleMatchingBench/benchGlobMatching1-opcache

🟥 execution_time [+135.235ns; +272.165ns] or [+5.082%; +10.229%]

scenario:SamplingRuleMatchingBench/benchGlobMatching4-opcache

🟥 execution_time [+100.780ns; +222.020ns] or [+3.637%; +8.013%]

scenario:SamplingRuleMatchingBench/benchRegexMatching1

🟥 execution_time [+66.579ns; +154.421ns] or [+4.576%; +10.613%]

scenario:SamplingRuleMatchingBench/benchRegexMatching2

🟥 execution_time [+70.178ns; +154.822ns] or [+4.814%; +10.621%]

scenario:SamplingRuleMatchingBench/benchRegexMatching3

🟥 execution_time [+52.541ns; +131.459ns] or [+3.584%; +8.968%]

scenario:SamplingRuleMatchingBench/benchRegexMatching4

🟥 execution_time [+49.059ns; +135.341ns] or [+3.353%; +9.251%]

scenario:SpanBench/benchDatadogAPI

🟥 execution_time [+2.003µs; +3.905µs] or [+2.544%; +4.960%]

scenario:SpanBench/benchOpenTelemetryAPI

🟥 execution_time [+21.049µs; +32.029µs] or [+2.657%; +4.042%]

scenario:SpanBench/benchOpenTelemetryAPI-opcache

🟥 mem_peak [+897.188KB; +897.196KB] or [+2.006%; +2.006%]

scenario:SpanBench/benchOpenTelemetryInteroperability

🟥 execution_time [+6.656µs; +9.080µs] or [+3.220%; +4.392%]

scenario:SpanBench/benchOpenTelemetryInteroperability-opcache

🟥 execution_time [+6.691µs; +11.268µs] or [+3.436%; +5.786%]

scenario:TraceAnnotationsBench/benchTraceAnnotationOverhead-opcache

🟥 mem_peak [+64.180KB; +64.184KB] or [+2.987%; +2.988%]

scenario:TraceSerializationBench/benchSerializeTrace

🟥 execution_time [+1.838ms; +1.865ms] or [+358.793%; +364.115%]

Signed-off-by: Alexandre Rulleau <alexandre.rulleau@datadoghq.com>

Bring the tracer C code into consistency with the already-rewritten v1-compatible span stub (tracer/ddtrace.stub.php), keeping the v04 wire format byte-identical (libdatadog v1 FFI is not yet available). - Regenerate ddtrace_arginfo.h from the stub; reorder the ddtrace_span_properties / ddtrace_root_span_data / ddtrace_span_stack structs to match the new property declaration order (PHP property offsets are bound to these C struct fields). - Drop SpanEvent/SpanLink JsonSerializable + jsonSerialize(); relocate that logic into serializer.c so the _dd.span_links / events meta blobs are produced with identical bytes. - Make component/spanKind sourced from the new SpanData properties, translated back into meta (span.kind/component) at serialize time so the v04 wire is unchanged. Register the new SpanKind class. - Remove dead code for stub-removed functions and the DD_TRACE_WARN_LEGACY_DD_TRACE config key; complete the userland integration-analytics removal (Integration.php + call sites); delete tests orphaned by removed functions and rewrite the dd_trace_reset helper tests without gutting their coverage. Refs APMLP-1197.

…DD_TRACE_WARN_LEGACY_DD_TRACE The config key DD_TRACE_WARN_LEGACY_DD_TRACE was removed from tracer/configuration.h, but metadata/supported-configurations.json was not regenerated, causing the 'Configuration Consistency' CI job to fail. Ran tooling/generate-supported-configurations.sh to sync.

RootSpanData extends SpanData, which already declares $env and $version. The v1-stub alignment accidentally re-declared them on RootSpanData (they were never on RootSpanData on master, and the ddtrace_root_span_data C struct has no separate env/version slots -- they are inherited SpanData slots). On PHP < 8.1 this redundant child redeclaration corrupts the RootSpanData property table: env/version are var_dump'd twice and propagatedTags loses its default, breaking tests/ext/active_span.phpt and span_clone.phpt on 7.0-8.0 (they passed on 8.1+). Removing the redeclaration from the stub and arginfo aligns stub=arginfo=C struct and restores consistent output across all versions; env/version remain available on RootSpanData via inheritance.

…on PHP 7 The new `attributes` property (stub default `= []`) was not materialized at span/stack creation. On PHP < 8.0 array-typed property defaults become null (see the ZVAL_EMPTY_ARRAY shim in functions.c) and are only lazily turned into arrays when touched; since `attributes` is never touched during a plain span lifecycle it var_dump'd as NULL on 7.0-7.4 (array(0){} on 8.0+), breaking tests/ext/active_span.phpt and span_clone.phpt. Force-materialize it in ddtrace_init_span and dd_alloc_span_stack (guarded to PHP < 8.0) so it is a consistent empty array on every supported version, matching its stub default.

The chore that dropped integration (App Analytics) auto-tagging removed Integration::addTraceAnalyticsIfEnabled and the per-integration DD_TRACE_<integration>_ANALYTICS_* config, so the _dd1.sr.eausr metric is no longer auto-added to integration spans. Align the tests: - Delete the 25 TraceSearchConfigTest.php files (Laravel, Lumen, Symfony, ZendFramework, Custom) whose sole subject was the removed per-integration trace-analytics config. - Drop the per-integration analytics setup + _dd1.sr.eausr metric assertions from the mixed PDO and SQLSRV integration tests, preserving all other span coverage. - Remove Curl's dedicated testTraceAnalytics method + its data provider (per-integration analytics config matrix) and the stale DD_CURL_ANALYTICS_ENABLED teardown-cleanup entries in Curl/Guzzle. The user-facing App Analytics API (Span::setMetric(Tag::ANALYTICS_KEY) -> TraceAnalyticsProcessor, Tag::ANALYTICS_KEY constant) is intentionally kept by this branch, so its tests (SpanTest, TraceAnalyticsProcessorTest, UserAvailableConstantsTest, OpenTelemetry, ext/test_special_attributes) are left intact.

Comment-only cleanup of the C span-consistency changes: trim the multi-line explanatory blocks in serializer.c, span.c, handlers_httpstreams.c and tracer_telemetry.c down to concise 1-2 line comments. No behavior change.

@deprecated

The user-facing App Analytics API is now a deprecated no-op: it remains callable (Tag::ANALYTICS_KEY, TraceAnalyticsProcessor, DD_TRACE_ANALYTICS_ENABLED stay defined) but no longer applies any behavior nor emits the _dd1.sr.eausr metric in-process or on the wire. - serializer.c: drop the DD_TRACE_ANALYTICS_ENABLED/web-analytics emission, stop converting the analytics.event meta key to the metric (still consumed), and skip _dd1.sr.eausr in the metrics serialization loop. - TraceAnalyticsProcessor::normalizeAnalyticsValue is now an empty no-op; Tag::ANALYTICS_KEY, the processor, and the api stubs are marked @deprecated. - Tests rewritten to assert the API is callable and emits no _dd1.sr.eausr.

Bump the libdatadog submodule to PR #2156's head (938c110), which brings in the v1 sidecar span encoder/decoder (#2145, #2174) via its main base. Regenerate components-rs/{common,sidecar}.h with cbindgen (exposes the new ddog_sidecar_send_trace_v1_shm / _bytes entrypoints and the ASM_RAW_RESPONSE_BODY remote-config capability) and mirror libdatadog's consolidated [workspace.dependencies] into the root Cargo.toml so the path-dependency crates resolve their { workspace = true } inheritance. Wire format is unchanged: v04 remains the default send path.

… V1 wire Add DD_TRACE_AGENT_PROTOCOL_VERSION (default "0.4"). When set to "1"/"1.0", assemble ddog_TracerMetadataV1 and call ddog_send_traces_to_sidecar_v1; otherwise keep the unchanged V0.4 sidecar send. Hard gate; no /info negotiation.

…OTOCOL_VERSION

Leiyks force-pushed the leiyks/dd-trace-php-v2 branch from 2531886 to b29cd49 Compare July 27, 2026 15:20

Leiyks force-pushed the leiyks/dd-trace-php-v2 branch 2 times, most recently from b6b5055 to 10c7edf Compare August 5, 2026 17:00

Leiyks added 19 commits August 6, 2026 14:34

wip: first draft

89df077

Signed-off-by: Alexandre Rulleau <alexandre.rulleau@datadoghq.com>

chore: drop integration analytics

69b13e2

Signed-off-by: Alexandre Rulleau <alexandre.rulleau@datadoghq.com>

chore(signals): drop stale TODO on legacy backtrace handler

85214b1

chore: bump libdatadog to v1 send FFI + regenerate headers

46b9a95

chore: bump libdatadog to include V1 /v1.0/traces routing fix

5625a4d

feat(tracer): emit native span links/events on the v1 path

a2bd342

feat(tracer): negotiate v1 via agent /info with v04 fallback

6a85e47

chore: regenerate supported-configurations.json for DD_TRACE_AGENT_PR…

3b077e1

…OTOCOL_VERSION

chore(tracer): tighten v1 comments

8d1b5a7

chore(libdatadog): sync submodule to v1 FFI branch tip

84351df

Leiyks force-pushed the leiyks/dd-trace-php-v2 branch from 10c7edf to 84351df Compare August 6, 2026 12:39

Navigation Menu

Uh oh!

feat(tracer): align C span code with v1-compatible stub API (v2 groundwork) - #4046

feat(tracer): align C span code with v1-compatible stub API (v2 groundwork)#4046
Leiyks wants to merge 19 commits into
masterfrom
leiyks/dd-trace-php-v2

Leiyks commented Jul 17, 2026 •

edited

Loading

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jul 17, 2026 •

edited by datadog-official Bot

Loading

Uh oh!

pr-commenter Bot commented Jul 17, 2026 •

edited

Loading

Explanation

More details about the CI and significant changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Leiyks commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

Changes

Deliberate scope decisions

Testing

Relationship to the V1 Efficient Trace Payload protocol

V1 protocol now enabled (behind a flag)

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jul 17, 2026 • edited by datadog-official Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

ℹ️ Info

Uh oh!

pr-commenter Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks [ tracer ]

Explanation

More details about the CI and significant changes

scenario:BM_TeaSapiSpindown

scenario:ContextPropagationBench/benchExtractHeaders64Bit-opcache

scenario:ContextPropagationBench/benchExtractTraceContext128Bit-opcache

scenario:ContextPropagationBench/benchInject128Bit-opcache

scenario:ContextPropagationBench/benchInject64Bit-opcache

scenario:HookBench/benchHookOverheadTraceMethod-opcache

scenario:SamplingRuleMatchingBench/benchGlobMatching1-opcache

scenario:SamplingRuleMatchingBench/benchGlobMatching4-opcache

scenario:SamplingRuleMatchingBench/benchRegexMatching1

scenario:SamplingRuleMatchingBench/benchRegexMatching2

scenario:SamplingRuleMatchingBench/benchRegexMatching3

scenario:SamplingRuleMatchingBench/benchRegexMatching4

scenario:SpanBench/benchDatadogAPI

scenario:SpanBench/benchOpenTelemetryAPI

scenario:SpanBench/benchOpenTelemetryAPI-opcache

scenario:SpanBench/benchOpenTelemetryInteroperability

scenario:SpanBench/benchOpenTelemetryInteroperability-opcache

scenario:TraceAnnotationsBench/benchTraceAnnotationOverhead-opcache

scenario:TraceSerializationBench/benchSerializeTrace

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Leiyks commented Jul 17, 2026 •

edited

Loading

datadog-datadog-prod-us1-2 Bot commented Jul 17, 2026 •

edited by datadog-official Bot

Loading

pr-commenter Bot commented Jul 17, 2026 •

edited

Loading