fix(guzzle): distributed tracing header injection in HyperF/Swoole environments

[PROFeNoM]

Description

Problem

Distributed tracing headers were not being injected in HyperF/Swoole environments, breaking trace continuity to downstream services.

Root Cause

1. HyperF uses CoroutineHandler instead of curl when running in Swoole coroutines
2. CoroutineHandler reads headers from the PSR-7 request object, not curl options
3. Our old integration only had post-hooks (via trace_method), which run AFTER the request is sent—too late to inject headers

Old flow:

transfer() → CoroutineHandler gets request → Headers missing → Request sent

Solution

Use install_hook instead of trace_method to add a pre-hook that injects distributed tracing headers into the PSR-7 request object BEFORE the handler executes.

New flow:

transfer() → PRE-HOOK injects headers → CoroutineHandler gets request with headers → Request sent

Important: The pre-hook must always call overrideArguments(), even when no headers are injected. Per ext/hook/uhook.c:

"hooks wishing to override args must do so unconditionally, even if the args are not changed. Otherwise, if overrideArguments was not called on the first time this function was traced, the JIT will have successfully traced the function and there's no going back."

Changes

• Convert transfer() instrumentation from trace_method to install_hook
• Add pre-hook to inject distributed tracing headers before request execution
• Ensure overrideArguments() is always called (required for JIT compatibility)
• Remove outdated comment about not supporting pre+post hooks

Testing

Verified by customer in production HyperF/Swoole environment: https://datadoghq.atlassian.net/browse/APMS-17909

Reviewer checklist

• Test coverage seems ok.
• Appropriate labels assigned.

[pr-commenter]

Benchmarks [ tracer ]

Benchmark execution time: 2025-12-30 15:48:29

Comparing candidate commit 27f1648 in PR branch alex/APMS-17909_guzzle-fix with baseline commit 575faf4 in branch master.

Found 1 performance improvements and 8 performance regressions! Performance is the same for 185 metrics, 0 unstable metrics.

scenario:MessagePackSerializationBench/benchMessagePackSerialization

• 🟥 execution_time [+7.216µs; +7.804µs] or [+7.141%; +7.724%]

scenario:MessagePackSerializationBench/benchMessagePackSerialization-opcache

• 🟥 execution_time [+14.798µs; +15.762µs] or [+14.660%; +15.615%]

scenario:SamplingRuleMatchingBench/benchRegexMatching1

• 🟥 execution_time [+116.107ns; +160.893ns] or [+9.909%; +13.732%]

scenario:SamplingRuleMatchingBench/benchRegexMatching2

• 🟥 execution_time [+96.859ns; +130.741ns] or [+8.377%; +11.308%]

scenario:SamplingRuleMatchingBench/benchRegexMatching3

• 🟥 execution_time [+109.215ns; +162.185ns] or [+9.365%; +13.907%]

scenario:SamplingRuleMatchingBench/benchRegexMatching4

• 🟥 execution_time [+80.593ns; +133.807ns] or [+6.883%; +11.428%]

scenario:SpanBench/benchDatadogAPI

• 🟥 execution_time [+1.642µs; +5.093µs] or [+2.570%; +7.972%]

scenario:SpanBench/benchOpenTelemetryAPI

• 🟥 mem_peak [+1.717MB; +1.720MB] or [+4.157%; +4.165%]

scenario:TraceSerializationBench/benchSerializeTrace

• 🟩 execution_time [-39.668µs; -27.832µs] or [-8.903%; -6.247%]

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.63%. Comparing base (9db6c6e) to head (aa69059).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3544      +/-   ##
==========================================
- Coverage   61.75%   61.63%   -0.12%     
==========================================
  Files         139      139              
  Lines       13051    13051              
  Branches     1712     1712              
==========================================
- Hits         8059     8044      -15     
- Misses       4228     4242      +14     
- Partials      764      765       +1     

see 3 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9db6c6e...aa69059. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.