feat(profiling): prototype heap-live allocation prefixes

[realFlowControl]

Note

this was my clanker trying out things, I have not looked at it yet, just wanted CI to run.

Description

This draft prototypes a max_align_t-sized allocation prefix for PHP 8.4+ heap-live profiling. Allocation hooks are installed during GINIT in passthrough mode and switch to prefixed pointers only after a clean non-full ZendMM reset, allowing malloc, realloc, and free to translate pointers without mixing pre-epoch and post-epoch allocations. Using the allocator's maximum alignment for the prefix preserves the alignment of returned pointers, including x86 SIMD-sensitive allocations.

The startup thread uses PHP's existing module-startup reset. Later ZTS threads use a chained TSRM new-thread-end handler that mirrors PHP startup's virtual-CWD cleanup around a non-full reset, establishing the epoch before the first request in ext-parallel, FrankenPHP, and Apache mod_event workers. Request flags gate sampling and heap-live tracking while pointer translation remains installed until GSHUTDOWN, where previous allocator handlers are restored before profiler TLS is destroyed. Neighboring custom allocators and USE_ZEND_ALLOC=0 remain in passthrough mode.

The prefix contains a magic value so an invariant violation aborts instead of forwarding a relocated pointer to ZendMM. The PR also documents allocation-footer and ZendMM chunk-map fallback designs that preserve pointers if the clean-epoch mechanism is not suitable for production.

Known PoC risks: TSRM exposes a singleton new-thread handler rather than an observer list, the callback runs while TSRM's mutex is held, and this draft intentionally leaves the process-global handler installed for the process lifetime. These need resolution before treating this as production-ready.

Validation performed:

• PHP 8.4 ZTS profiler PHPT suite: 39 passed, 10 skipped, 0 failed.
• PHP 8.5 ZTS profiler PHPT suite: 40 passed, 9 skipped, 0 failed.
• PHP 8.4 and PHP 8.5 NTS/ZTS full language-test CI jobs passed on real amd64, including upstream xxhash_seed.phpt.
• Prefix add/remove unit test verifies that allocator alignment is preserved.
• 100 sequential ext-parallel runtime creations completed without crashes or deadlocks.
• FrankenPHP 1.12.4 regular and persistent worker modes completed first-request and concurrent allocation stress.
• Apache mpm_event with the PHP 8.4 ZTS apache2handler completed first-request and concurrent allocation stress.
• USE_ZEND_ALLOC=0 remained in passthrough mode.
• PHP 8.3 NTS and PHP 8.4 NTS builds succeeded; the PHP 8.4 debug-ZTS-ASAN prefix test passed.

Reviewer checklist

• Test coverage seems ok.
• Appropriate labels assigned.

[datadog-prod-us1-6]

 

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 3 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-php | min install tests     

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

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

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🔄 Datadog auto-retried 1 job - 1 passed on retry

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 54.11% (+0.00%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 4fdfcd5 | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks [ profiler ]

Benchmark execution time: 2026-07-15 12:52:54

Comparing candidate commit 4fdfcd5 in PR branch florian/no-jira-heap-live-prefix-poc with baseline commit 024fe4a in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 28 metrics, 8 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 ----------------------------------'