Track heap profiler liveness with ObjectSpace::WeakMap instead of _id2ref

[eregon]

ObjectSpace._id2ref is a dead end for the heap profiler: it was removed in Ruby 4.1 ([Feature #22135]), is deprecated in 4.0 ([Feature #15408]), and has a history of crashes such as returning unrelated live objects under lazy sweeping ([Bug #22200]).

Each heap recorder now owns an ObjectSpace::WeakMap mapping record_id -> object. A WeakMap entry is dropped as soon as either side is collected, so pairing an immortal fixnum key with the tracked object as the (weak) value gives us exactly the weak reference we need: reading the key back returns the object while it's alive, and nil once it's gone. This also replaces a rb_rescue2 + raise-per-dead-object with a plain lookup.

While here, drop rb_obj_id from the heap path in favour of a per-recorder monotonic counter. Asking for an object_id mutates the profiled application's objects -- a shape/fields transition on Ruby 4, and two st_table entries plus FL_SEEN_OBJ_ID on Ruby 3 -- so not needing it makes heap profiling less intrusive. It also lets us drop NO_IMEMO_OBJECT_ID (Ruby 4 was silently dropping IMEMO heap samples), the bignum-exhaustion failure mode, and the duplicate-id check, since ids are now unique by construction.

Deferred recording becomes unconditional. WeakMap#[]= is a Ruby method call that allocates, and neither is safe inside the newobj tracepoint on Ruby < 4.0: ruby_xmalloc can trigger a GC there, as Ruby only added rb_gc_local_disable_no_rest() around the hook in 4.0. So the object reference is always buffered and the weak map entry is added later from the after_allocation postponed job. This removes the USE_DEFERRED_HEAP_ALLOCATION_RECORDING split rather than widening it, and needs a rb_postponed_job_register_one fallback for Ruby < 3.3. It also restores the "consecutive recording starts without end" guard, which was a no-op in deferred mode. Note that buffer-full drops (deferred_recordings_skipped_buffer_full) now become possible on Ruby < 4, which previously committed inline.

Heap profiling is force-disabled on Ruby 3.1.0-3.1.3 and 3.2.0-3.2.2, where ObjectSpace::WeakMap can corrupt its internal state during compaction ([Bug #19529], fixed in 3.1.4 and 3.2.3). The Ruby 4.1 guard is removed.

Note that enabling heap profiling on Ruby 4.1 end to end additionally needs a datadog-ruby_core_source release with 4.1 headers, which the profiler extension does not build without today.

Verified: full profiling suite on 3.1.7 (docker), 3.2.11, 3.3.11, 3.4.9 and 4.0.6, covering both WeakMap implementations (finalizer-based on 3.1/3.2, weak-reference-based on 3.3+).

What does this PR do?

^

Motivation:

Make heap profiling work reliably.

Change log entry

Yes. Heap profiling now uses ObjectSpace::WeakMap instead of ObjectSpace._id2ref, avoiding many issues related to ObjectSpace._id2ref. Heap live size profiling is no longer disabled on Ruby 4.0 as it works reliably now.

Additional Notes:

How to test the change?

[datadog-prod-us1-4]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 0.00%
• Overall Coverage: 90.00% (+0.03%)

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

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-08-13 14:28:43

Comparing candidate commit 74820ac in PR branch bye-bye-id2ref with baseline commit 4850645 in branch master.

📊 Benchmarking dashboard

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

Unstable benchmarks

These benchmarks have a confidence interval too wide to call a change; treat them as noise rather than signal.

scenario:tracing - trace.to_digest - Continue

• unstable throughput [-1289.197op/s; +1807.448op/s] or [-4.441%; +6.227%]

[eregon]

LONG2NUM->LONG2FIX here, that's only OK if all record IDs are always in Fixnum range.
But also it's unsafe for us to use Bignum in the weakmap because then we'd need to hold onto them, otherwise they could GC and remove the entry altogether.

[eregon]

Maybe we can completely remove this now, though there is still a special case for T_NODE.
I haven't looked if that crash was related to _id2ref + memsize issues on Ruby 4.0.

[eregon]

This seems actually a really cool trick to reliably not hold onto an Object, which is otherwise very difficult to achieve in CRuby (from ruby/spec experience).

[eregon]

This was outdated, heap profiling was already 3.1+

[eregon]

I self-reviewed, it looks pretty reasonable and not so big, ready for other 👀 to review.

[eregon]

It works fine
From

DD_TRACE_DEBUG=true DD_PROFILING_EXPERIMENTAL_SHOW_CLASSES_ENABLED=true DD_PROFILING_ENABLED=true DD_PROFILING_ALLOCATION_ENABLED=true DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED=true DD_PROFILING_EXPERIMENTAL_HEAP_SIZE_ENABLED=true DD_SERVICE=benoit-testing bundle exec ddprofrb exec ruby -rbenchmark -e 'def foo; Array.new(1000) { Object.new }; end; p Benchmark.realtime { 70_000.times { foo } }'

[eregon]

Benchmark on Ruby 3.4 & 3.2, on macOS:
TLDR: ~1% faster on 3.4, ~1% slower on 3.2, seems fine.

Benchmarks: ObjectSpace._id2ref → ObjectSpace::WeakMap

Method

• Branch vs its merge base (48506456a3), built in two separate worktrees on the same machine.
• Runs are interleaved (branch, baseline, branch, baseline, …) within each repetition, so thermal drift affects both sides equally.
• HEAP_SAMPLES=true HEAP_SIZE=true. Ruby 3.4.9 = 3 reps, Ruby 3.2.11 = 4 reps.
• profiling_allocation.rb measures BasicObject.new throughput; heap profiling enabled via the new HEAP_SAMPLES option. It also reports a no-profiler control, which gives a per-run noise estimate.
• profiling_memory_sample_serialize.rb measures sample + serialize (6000 samples/iteration at stack depths up to 400). RETAIN_EVERY is used to isolate the liveness-check path:
  • RETAIN_EVERY=1 → all 6000 tracked objects alive ⇒ 6000 lookup hits
  • RETAIN_EVERY=100000 → ~none alive ⇒ ~5999 lookup misses
  • RETAIN_EVERY=10 (default) → mixed, 600 live / 5400 dead

Environment: arm64 macOS laptop, no CPU pinning. Treat sub-1% differences as noise unless the ranges are disjoint.

Ruby 3.4.9 (rb_gc_mark_weak-based WeakMap), 3 reps

measurement	branch (WeakMap)	baseline (_id2ref)	Δ
profiling_allocation, no profiler (control)	24.151, 24.148, 24.202 → 24.167M i/s	24.010, 23.925, 23.983 → 23.973M i/s	+0.8% (noise floor)
profiling_allocation, heap on	14.632, 14.728, 14.738 → 14.699M i/s	14.627, 14.825, 14.590 → 14.681M i/s	+0.1%
sample+serialize, RETAIN_EVERY=10	5.486, 5.530, 5.515 → 5.510 i/s	5.456, 5.449, 5.467 → 5.457 i/s	+1.0% (disjoint)
sample+serialize, RETAIN_EVERY=1 (hits)	4.559, 4.588, 4.589 → 4.579 i/s	4.586, 4.588, 4.575 → 4.583 i/s	−0.1%
sample+serialize, RETAIN_EVERY=100000 (misses)	5.647, 5.645, 5.652 → 5.648 i/s	5.576, 5.573, 5.573 → 5.574 i/s	+1.3% (disjoint)

Ruby 3.2.11 (finalizer-based WeakMap), 4 reps

measurement	branch (WeakMap)	baseline (_id2ref)	Δ
profiling_allocation, no profiler (control)	25.561, 25.661, 25.708, 25.729 → 25.665M i/s	25.504, 25.790, 25.223, 25.555 → 25.518M i/s	+0.6% (noise floor)
profiling_allocation, heap on	15.335, 15.422, 15.509, 15.470 → 15.434M i/s	15.401, 15.440, 15.299, 15.318 → 15.365M i/s	+0.4% (−0.1% normalised to own control)
sample+serialize, RETAIN_EVERY=10	5.167, 5.167, 5.154, 5.151 → 5.160 i/s	5.147, 5.173, 5.131, 5.123 → 5.144 i/s	+0.3%
sample+serialize, RETAIN_EVERY=1 (hits)	4.351, 4.338, 4.348, 4.245 → 4.321 i/s	4.409, 4.387, 4.377, 4.345 → 4.380 i/s	−1.3%
sample+serialize, RETAIN_EVERY=100000 (misses)	5.302, 5.280, 5.286, 5.311 → 5.295 i/s	5.257, 5.230, 5.307, 5.287 → 5.270 i/s	+0.5%

Side by side

	Ruby 3.2 (finalizer-based WeakMap)	Ruby 3.4 (rb_gc_mark_weak)
allocation path	neutral	neutral
liveness lookup hits	−1.3% (slower)	−0.1% (neutral)
liveness lookup misses	+0.5% (marginal, ranges overlap)	+1.3% (disjoint ranges)
default mix (600 live / 5400 dead)	+0.3% (marginal)	+1.0% (disjoint)

Interpretation

On Ruby 3.3+ the win comes entirely from the miss path. _id2ref signals "object is gone" by raising RangeError, so the old code paid rb_rescue2 setup plus a raise-and-rescue for every dead object; the WeakMap simply returns nil. Quantified on 3.4: 179.41 → 177.06 ms per iteration over ~5999 dead-object lookups ≈ 390 ns saved per dead-object liveness check. The default-mix +1.0% is just that win scaled by the proportion of dead records.

On Ruby 3.2 that gain is largely eaten. wmap_lookup there does more work per lookup — an is_pointer_to_heap + is_live_object check on the retrieved value, plus the obj2wmap inverse table — versus 3.3+'s bare Qundef test. So hits get ~1% slower and the miss-path gain shrinks into the noise, netting roughly neutral overall.

The allocation path is unaffected on both versions. This is the reassuring one: making recording deferred on every Ruby (buffer write + postponed job, previously Ruby 4 only) costs nothing measurable, because it also removed the rb_obj_id call that mutated every sampled object. Notably, the per-object finalizer that wmap_aset registers on Ruby < 3.3 — the known cost of supporting 3.1/3.2 with WeakMap rather than raising the minimum to 3.3 — does not show up measurably here either.

For reference, the cost of enabling heap profiling at all (unchanged by this PR): ~1.64x on BasicObject.new on 3.4 (41 ns → 68 ns) and ~1.66x on 3.2 (39 ns → 65 ns).

Caveats

• The only result I'd call solid on 3.2 is the −1.3% on hits: it pointed the same direction in two independent runs (−0.9%, then −1.3%). Everything else on 3.2 is inside the ~0.6% noise floor.
• sample+serialize spends ~30 µs per sample on stack walking, so the liveness check is a thin slice of each iteration. Sub-1% end-to-end movements may correspond to considerably larger relative changes in the update itself. Quantifying that would need a micro-benchmark timing heap_recorder_update directly, which the current test-only API can't do because the update self-throttles (it skips when the GC generation hasn't advanced, and skips records at gen_age >= OLD_AGE).
• No CPU pinning. An earlier 3.2 run was discarded because one sample came in ~70x slow (0.063 i/s vs ~4.4) during a period of machine contention; the numbers above are from a clean run at 99% CPU with no outliers.