docs(profiling): document DD_HEAP_SAMPLING_ENABLED vs native-heap gate

Review asked how ddtrace config and the libdatadog process-start bypass interact; record the two independent AND-gates on the install path.

Author: vlad-scherbich

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

@@ -10,6 +10,16 @@
 ``ddheap:free``) USDT sites fire; the Full Host eBPF profiler attaches uprobes.
 Nothing is collected or uploaded from Python.
 
+Two independent runtime gates, both required for GOT to be patched:
+
+* ``DD_PROFILING_NATIVE_HEAP_ENABLED`` — ddtrace install gate (also the
+  setup.py build gate). When false, this module is not imported from the
+  profiler and ``install()`` is never called.
+* ``DD_HEAP_SAMPLING_ENABLED`` — libdatadog process-start bypass (unset =
+  on; ``0``/``false``/``no``/``off`` disables). Honored inside
+  ``install_heap_overrides``; a falsey value leaves the GOT untouched and
+  ``install()`` returns False. ddtrace does not set or wrap this variable.
+
 ``live_heap_enabled()`` is a compile-time property of the loaded artifact
 (default-on ``live-heap`` feature): True when the cdylib stamps retain flags and
 emits ``ddheap:free``. False if the cdylib is missing, alloc-only

ddtrace/profiling/profiler.py

@@ -381,6 +381,8 @@ def _start_service(self) -> None:
         """Start the profiler."""
         # See DD_PROFILING_NATIVE_HEAP_ENABLED. install() is permanent; children
         # inherit the patched GOT (and the activator skips a redundant re-install).
+        # libdatadog may still refuse the patch via DD_HEAP_SAMPLING_ENABLED
+        # (unset = on); that is not a ddtrace setting — see heap_gotter docs.
         if profiling_config.native_heap.enabled:
             from ddtrace.internal.datadog.profiling import heap_gotter
 

src/native_heap_gotter/lib.rs

@@ -10,6 +10,13 @@
 /// Returns the result of `install_heap_overrides`, i.e. whether at least one
 /// allocator symbol's GOT entry was resolved and patched (so hooks will run).
 ///
+/// libdatadog independently honors `DD_HEAP_SAMPLING_ENABLED` (unset =
+/// enabled; `0`/`false`/`no`/`off` disables). That check lives inside
+/// `install_heap_overrides`: a falsey value returns false without touching
+/// the GOT. Distinct from `DD_PROFILING_NATIVE_HEAP_ENABLED`, which is the
+/// ddtrace-side gate that decides whether this function is called. This
+/// wrapper does not read or set the libdatadog env var.
+///
 /// After a successful install, a `fork()` child inherits the mapping and the
 /// patched GOT, so a second native install is usually unnecessary. Upstream has
 /// no `pthread_atfork` child reset for the process-global registry mutex