profiling: prototype heap-live tracking heap

[realFlowControl]

Description

This draft prototypes heap-live tracking with a lazy secondary ZendMM heap on PHP 8.4+. Allocation sample candidates are routed to the secondary heap, allowing ordinary frees to determine that they are untracked from their chunk owner without hashing the pointer or touching the shared DashMap.

The secondary heap obtains its 2 MiB chunks from the primary heap through zend_mm_startup_ex(), preserving conservative PHP memory accounting and memory-limit enforcement. Small and large allocations use one aligned chunk-header owner load and pointer comparison; huge allocations fall back to is_zend_ptr(). The DashMap remains the source of truth for candidates that completed stack collection and message submission.

Reallocations already owned by the secondary heap remain there. Sampled primary reallocations are moved by allocating from the secondary heap, copying the old contents, and freeing the primary allocation. Allocation hooks now remain installed through ZendMM request shutdown so allocations can continue to be dispatched to the correct heap after module RSHUTDOWN. GC, fork handling, tracked-sample cleanup, and restoration of neighboring handlers are included.

PHP versions without zend_mm_set_custom_handlers_ex() retain the existing tracking path. Neighboring custom allocators also retain the existing per-free map lookup.

Benchmark

A local PHP 8.5 synthetic allocation/free churn benchmark at the default 4 MiB sampling distance improved from a 192.2 ms median on origin/master to 188.7 ms with the direct chunk-owner check, approximately 1.8%. With heap-live disabled, the measured difference was approximately 0.15%.

Verification

• cargo test -p datadog-php-profiling --lib: 21 passed.
• Clippy NTS dead-code validation passed for local PHP 8.2 and PHP 8.5 builds after matching the helper cfg to the PHP 8.4+ allocator module; the local macOS run additionally allowed the clippy::ptr-arg lint emitted by got_macho.rs.
• Heap-live PHPT selection: 3 passed, including the new allocation/reallocation stress test.
• PHP built-in server: 100 repeated requests in one process completed successfully.
• Focused fork, huge-allocation, realloc, free, and gc_mem_caches() checks passed.
• Release builds and smoke tests passed with local PHP 8.4 and PHP 8.5.

Known limitations

• The fast path depends on the private ZendMM invariant that _zend_mm_chunk::heap is the first field.
• Creating the tracked heap charges the primary heap in 2 MiB chunk increments.
• The pre-allocation tracker-capacity check can race with the later DashMap insertion in ZTS. Before productionizing this, sample candidates should always use the secondary heap and the cap should only govern metadata insertion.

Reviewer checklist

• Test coverage seems ok.
• Appropriate labels assigned.

[datadog-datadog-prod-us1]

 

✨ Unblock PR with BitsAI

⚠️ Warnings

🚦 8 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-php | merge-gate     

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

DataDog/apm-reliability/dd-trace-php | test_web_drupal_95: [7.4, cgi-fcgi]     

View all 8 failed jobs.

ℹ️ 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.08% (-0.04%)

Useful? React with 👍 / 👎

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

[pr-commenter]

Benchmarks [ profiler ]

Benchmark execution time: 2026-07-22 07:24:00

Comparing candidate commit e96f91c in PR branch florian/no-jira-heap-live-second-heap-poc with baseline commit 17a0855 in branch master.

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