feat(profiling): native live-heap (ddheap:free) for native allocations

Make native heap profiling alloc + live/retained heap in one artifact.
A gotter build (DD_PROFILING_NATIVE_HEAP_BUILD=1) now always compiles the
`live-heap` cargo feature (a Cargo default), so it flags sampled allocations
and emits the ddheap:free USDT alongside ddheap:alloc, letting the Full Host
eBPF profiler reconcile frees against allocations and report retained memory
rather than only cumulative allocations.

There is a single build knob: the earlier separate DD_PROFILING_NATIVE_HEAP_LIVE
gate (an artifact of the incremental Phase 1 -> live-heap build-out) is removed
and folded into DD_PROFILING_NATIVE_HEAP_BUILD.

- wrapper crate: `live-heap` is a default feature, forwarding to the upstream
  gotter/sampler crate (C define DD_HEAP_LIVE_TRACKING); the free GOT hook is
  always interposed, the ddheap:free USDT + alloc-side retain flagging come with
  the feature
- C ABI ddtrace_heap_gotter_live_heap_enabled() capability query (defensive:
  reflects the actual loaded artifact, so an older alloc-only cdylib reads false)
- activator binds it defensively, exposes live_heap_enabled()
- profiler reports armed mode (live-heap vs allocation-only)

The default (non-gotter) build is unchanged. Runtime arming is still gated by
DD_PROFILING_NATIVE_HEAP_ENABLED.

Author: vlad-scherbich

ddtrace/internal/datadog/profiling/heap_gotter/__init__.py

@@ -4,14 +4,25 @@
 libdatadog's ``libdd-profiling-heap-gotter-ffi``; see ``src/native_heap_gotter``)
 and drives it through a tiny, stable C ABI:
 
-    bool ddtrace_heap_gotter_install(void);      # install + report success
-    bool ddtrace_heap_gotter_is_installed(void); # current install state
+    bool ddtrace_heap_gotter_install(void);           # install + report success
+    bool ddtrace_heap_gotter_is_installed(void);       # current install state
+    bool ddtrace_heap_gotter_live_heap_enabled(void);  # built with ddheap:free?
 
 Calling ``install()`` patches the process's GOT entries for heap allocation
-symbols so that Datadog's ``ddheap:alloc`` (Phase 1: allocation-only) USDT probe
-sites fire on sampled allocations. The Full Host eBPF profiler then attaches
-uprobes to those sites to collect native allocation flamegraphs. There is
-nothing to collect or upload from the Python side — this only *arms* the probes.
+symbols so that Datadog's ``ddheap:alloc`` USDT probe sites fire on sampled
+allocations. The Full Host eBPF profiler then attaches uprobes to those sites to
+collect native allocation flamegraphs. There is nothing to collect or upload
+from the Python side — this only *arms* the probes.
+
+``live_heap_enabled()`` reports whether the loaded cdylib was *built* with
+live-heap tracking, in which case it also emits the ``ddheap:free`` USDT and
+stamps a per-allocation retain flag so the FH profiler can reconcile frees
+against allocations for a live/retained-heap view. Live-heap is a default of the
+gotter build, so any current cdylib reports ``True``; the query stays as a
+defensive check that reflects the *actual* loaded artifact — an older alloc-only
+cdylib (or a cdylib built before this symbol existed) reports ``False`` (the
+symbol is bound defensively). This is a compile-time property, not a runtime
+toggle.
 
 Fail-closed by design: if the cdylib is missing (the default, since it only
 ships when built with ``DD_PROFILING_NATIVE_HEAP_BUILD=1``) or anything goes
@@ -37,6 +48,11 @@
 is_available: bool = False
 failure_msg: str = ""
 
+# Whether the loaded cdylib was built with live-heap tracking (ddheap:free +
+# retain flagging). Compile-time property of the artifact; see module docstring.
+# Stays False when the cdylib is absent or was built allocation-only.
+_live_heap_available: bool = False
+
 _lib: ctypes.CDLL | None = None  # kept alive for process lifetime; never dlclose'd
 
 
@@ -69,6 +85,16 @@ def _library_path() -> str:
 
     is_available = True
 
+    # Bind the live-heap capability query defensively: it only exists on cdylibs
+    # built at/after Phase 2. A missing symbol (older alloc-only build) simply
+    # leaves live-heap reported as unavailable rather than failing the load.
+    try:
+        _lib.ddtrace_heap_gotter_live_heap_enabled.argtypes = []
+        _lib.ddtrace_heap_gotter_live_heap_enabled.restype = ctypes.c_bool
+        _live_heap_available = bool(_lib.ddtrace_heap_gotter_live_heap_enabled())
+    except AttributeError:
+        _live_heap_available = False
+
 except Exception as e:
     failure_msg = str(e)
     _lib = None
@@ -96,3 +122,15 @@ def is_installed() -> bool:
         return bool(_lib.ddtrace_heap_gotter_is_installed())
     except Exception:
         return False
+
+
+def live_heap_enabled() -> bool:
+    """Return whether the loaded cdylib was built with live-heap tracking.
+
+    Live-heap is a default of the gotter build, so any current cdylib returns
+    True: it emits the ``ddheap:free`` USDT and stamps a per-allocation retain
+    flag so the FH profiler can reconcile frees against allocations. A missing
+    cdylib, or an older alloc-only one, returns False. Compile-time property; it
+    does not change over the process lifetime.
+    """
+    return _live_heap_available

ddtrace/profiling/profiler.py

@@ -389,7 +389,11 @@ def _start_service(self) -> None:
 
             try:
                 if heap_gotter.install():
-                    LOG.debug("Native heap profiling armed (GOT overrides installed)")
+                    # live-heap (ddheap:free + retain flagging) is a build-time
+                    # property of the cdylib, not a runtime toggle; report which
+                    # mode was actually armed for observability.
+                    mode = "live-heap" if heap_gotter.live_heap_enabled() else "allocation-only"
+                    LOG.debug("Native heap profiling armed (GOT overrides installed, %s)", mode)
                 else:
                     LOG.debug("Native heap profiling requested but GOT overrides were not installed")
             except Exception:

releasenotes/notes/native-heap-live-heap-freeprobe-1ec2c087183201e6.yaml

@@ -0,0 +1,11 @@
+features:
+  - |
+    profiling: Extend the experimental, opt-in native (C/C++) heap profiling with
+    live/retained-heap tracking. A gotter build (``DD_PROFILING_NATIVE_HEAP_BUILD=1``)
+    now flags sampled allocations and emits the ``ddheap:free`` USDT probe in
+    addition to ``ddheap:alloc``, so the Datadog eBPF profiler can reconcile frees
+    against allocations and report retained memory, not just cumulative
+    allocations. This is a build-time capability; the default (non-gotter) build is
+    unchanged. Runtime arming is still gated by
+    ``DD_PROFILING_NATIVE_HEAP_ENABLED=true``, and the whole feature is a no-op when
+    disabled.

setup.py

@@ -128,12 +128,15 @@
 
 BUILD_PROFILING_NATIVE_TESTS = os.getenv("DD_PROFILING_NATIVE_TESTS", "0").lower() in ("1", "yes", "on", "true")
 
-# Opt-in build of the native heap-gotter cdylib (Phase 1: allocation-only native
-# heap profiling via GOT rewriting, driven at runtime by the FH eBPF profiler).
-# Off by default so mainline wheels are not pinned to a moving libdatadog `main`
-# SHA and normal builds don't pay the extra cargo fetch/compile. The staging A/B
-# harness sets this to bake the artifact into its custom wheels; runtime install
-# is separately gated by DD_PROFILING_NATIVE_HEAP_ENABLED.
+# Opt-in build of the native heap-gotter cdylib: allocation + live/retained-heap
+# native heap profiling via GOT rewriting, driven at runtime by the FH eBPF
+# profiler. When set, the cdylib is built with the `live-heap` cargo feature (a
+# Cargo default), so it emits both the `ddheap:alloc` and `ddheap:free` USDTs and
+# the FH profiler can reconcile frees against allocations for a retained-heap
+# view. Off by default so mainline wheels are not pinned to a moving libdatadog
+# `main` SHA and normal builds don't pay the extra cargo fetch/compile. The
+# staging A/B harness sets this to bake the artifact into its custom wheels;
+# runtime install is separately gated by DD_PROFILING_NATIVE_HEAP_ENABLED.
 BUILD_NATIVE_HEAP_GOTTER: bool = os.getenv("DD_PROFILING_NATIVE_HEAP_BUILD", "0").lower() in ("1", "yes", "on", "true")
 
 CURRENT_OS = platform.system()
@@ -1056,6 +1059,9 @@ def build_heap_gotter(self) -> None:
             # render to stderr in human form.
             "--message-format=json-render-diagnostics",
         ] + DD_CARGO_ARGS
+        # `live-heap` is a default cargo feature (see Cargo.toml), so the built
+        # cdylib always emits both the `ddheap:alloc` and `ddheap:free` USDTs
+        # (verifiable via `readelf -n`) and stamps per-allocation retain flags.
         proc: subprocess.CompletedProcess[str] = subprocess.run(
             cargo_cmd, check=True, stdout=subprocess.PIPE, text=True
         )

src/native_heap_gotter/Cargo.toml

@@ -14,10 +14,13 @@
 #     over the upstream crate's pure-Rust API, so the Python ctypes activator
 #     links against fixed, unmangled symbol names and gets a plain `bool`.
 #
-# Phase 1 is allocation-only: the `live-heap` cargo feature of the gotter is
-# intentionally NOT enabled, so the free-path USDT (`ddheap:free`) and its
-# per-free overhead stay compiled out. Enabling live-heap later just adds the
-# `live-heap` feature on the `libdd-profiling-heap-gotter` dependency below.
+# Native heap profiling is alloc + live/retained heap in one artifact: `live-heap`
+# is a DEFAULT cargo feature (see the [features] block), so any gotter build
+# (DD_PROFILING_NATIVE_HEAP_BUILD=1) emits both the `ddheap:alloc` and
+# `ddheap:free` USDTs, letting the FH eBPF profiler reconcile frees against
+# allocations for a retained-heap view. There is no separate alloc-only build
+# gate — the free-path USDT + per-allocation retain flagging come from forwarding
+# to `libdd-profiling-heap-gotter/live-heap` (see the [features] block below).
 [package]
 name = "ddtrace-heap-gotter"
 version = "0.1.0"
@@ -43,8 +46,22 @@ codegen-units = 1
 # live eBPF uprobe attach. Never enabled for shipped wheels.
 test-support = ["libdd-profiling-heap-gotter/test-support"]
 
+# AIDEV-NOTE: `live-heap` is a *build-time* feature (not a runtime knob) and is a
+# DEFAULT feature, so every gotter build includes it. It forwards to
+# libdd-profiling-heap-gotter/live-heap -> libdd-profiling-heap-sampler/live-heap,
+# whose build.rs turns the CARGO_FEATURE_LIVE_HEAP cargo feature into the C define
+# DD_HEAP_LIVE_TRACKING=1. That define makes (a) dd_probe_free emit the
+# `ddheap:free` USDT (otherwise the note is absent from .note.stapsdt) and (b) the
+# alloc side stamp the per-allocation retain flag so the free side can reconcile
+# it. The `free` GOT hook itself is always interposed upstream. Because the
+# `ddheap:free` ELF note is a property of the compiled artifact, live-heap is a
+# build-time property and cannot be flipped by the Python activator at runtime.
+default = ["live-heap"]
+live-heap = ["libdd-profiling-heap-gotter/live-heap"]
+
 [dependencies]
 # Pinned to the published crates.io release (Phase 1.5 migration off the
-# libdatadog `main` git pin). `default-features = false` keeps the
-# allocation-only surface: `live-heap` stays opt-in and off for Phase 1.
+# libdatadog `main` git pin). `default-features = false` disables the upstream
+# crate's own defaults; our `live-heap` feature (a default here) enables exactly
+# the live-heap surface we need on top.
 libdd-profiling-heap-gotter = { version = "1.0.0", default-features = false }

src/native_heap_gotter/lib.rs

@@ -11,7 +11,9 @@
 //! `heap_overrides_are_installed`); it is not a C-ABI surface. Here we re-export
 //! those calls as fixed, unmangled `extern "C"` entry points returning a plain
 //! `bool`, so the Python ctypes side links against stable symbol names and gets
-//! a trivial success signal.
+//! a trivial success signal. We also expose
+//! `ddtrace_heap_gotter_live_heap_enabled`, which reports whether this artifact
+//! was built with live-heap tracking (Phase 2: `ddheap:free` + retain flagging).
 //!
 //! Installation is permanent and process-global: the GOT entries patched by
 //! `install` point at functions inside the linked-in gotter code, so this
@@ -50,6 +52,29 @@ pub extern "C" fn ddtrace_heap_gotter_is_installed() -> bool {
     libdd_profiling_heap_gotter::heap_overrides_are_installed()
 }
 
+/// Report whether this cdylib was built with live-heap tracking (Phase 2:
+/// the `ddheap:free` USDT + per-allocation retain flagging), so the free side
+/// can be reconciled against allocations. This is a *compile-time* property of
+/// the shipped artifact — alloc-only builds return `false`, live-heap builds
+/// return `true` — and is NOT a runtime toggle. The Python activator surfaces
+/// it so the profiler can report which native-heap mode is armed.
+///
+/// AIDEV-NOTE: `cfg!(feature = "live-heap")` here is our crate's own feature,
+/// declared in Cargo.toml as a pure forward to
+/// `libdd-profiling-heap-gotter/live-heap`. It is true iff the artifact was
+/// built with `--features live-heap`, which is exactly the condition under
+/// which the sampler compiled in DD_HEAP_LIVE_TRACKING and emits `ddheap:free`.
+/// Keep this boolean in lockstep with the Cargo feature so the runtime signal
+/// never disagrees with the ELF `.note.stapsdt` reality.
+///
+/// # Safety
+///
+/// C ABI entry point with no arguments and no pointers; always safe to call.
+#[no_mangle]
+pub extern "C" fn ddtrace_heap_gotter_live_heap_enabled() -> bool {
+    cfg!(feature = "live-heap")
+}
+
 /// Test-only: number of times a patched hook has run in this process. Lets
 /// integration tests prove the patched GOT was actually exercised without a
 /// live eBPF attach. Only present when built with the `test-support` feature;

tests/profiling/test_native_heap_gotter.py

@@ -30,13 +30,19 @@ def test_native_heap_gotter_smoke() -> None:
         # Wheel built without the gotter cdylib: strictly a no-op.
         assert heap_gotter.install() is False
         assert heap_gotter.is_installed() is False
+        # live_heap_enabled must be a safe False no-op when the cdylib is absent.
+        assert heap_gotter.live_heap_enabled() is False
     else:
         # Native-heap build: arming must take effect and be idempotent.
         assert heap_gotter.is_installed() is False
         assert heap_gotter.install() is True
         assert heap_gotter.is_installed() is True
         assert heap_gotter.install() is True
 
+        # live-heap is a compile-time property; the query must return a bool and
+        # never crash regardless of whether this build enabled the feature.
+        assert isinstance(heap_gotter.live_heap_enabled(), bool)
+
         # Generate allocation pressure; this must not crash with the patched GOT.
         blobs: list[tuple[str, int]] = []
         for i in range(200):