docs(profiler): mark Java live heap profiling as GA#35802
Open
docs(profiler): mark Java live heap profiling as GA#35802
Conversation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
Preview links (active after the
|
buraizu
reviewed
Apr 8, 2026
Contributor
buraizu
left a comment
buraizu
left a comment
There was a problem hiding this comment.
Thanks for the PR, this looks good overall but just requesting a minor clarification in the new note
- DD_PROFILING_HEAP_ENABLED is the master toggle (gates both ddprof and JFR fallback), not a legacy key - DD_PROFILING_DDPROF_LIVEHEAP_ENABLED is ddprof-specific override only - Split disable instructions into two cases: all vs ddprof-only - Add DD_PROFILING_HEAP_ENABLED to config reference table Rationale: source code in dd-trace-java confirms DD_PROFILING_HEAP_ENABLED gates both engines; previous docs had the relationship backwards
buraizu
reviewed
Apr 9, 2026
Contributor
buraizu
left a comment
buraizu
left a comment
There was a problem hiding this comment.
Thanks for that update @jbachorik, left just a few additional suggestions — but happy to reconsider any of them if I've misunderstood anything.
|
|
||
| | Environment variable | System property | Description | | ||
| |---------------------|-----------------|-------------| | ||
| | `DD_PROFILING_HEAP_ENABLED` | `-Ddd.profiling.heap.enabled` | Master toggle for all live heap profiling, including both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback (default: true on supported platforms since v1.61.0) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `DD_PROFILING_HEAP_ENABLED` | `-Ddd.profiling.heap.enabled` | Master toggle for all live heap profiling, including both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback (default: true on supported platforms since v1.61.0) | | |
| | `DD_PROFILING_HEAP_ENABLED` | `-Ddd.profiling.heap.enabled` | Main toggle for all live heap profiling, including both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback (default: true on supported platforms since v1.61.0) | |
| : The amount of heap memory allocated by each method that has not yet been garbage collected. This is useful for investigating the overall memory usage of your service and identifying potential memory leaks.<br /> | ||
| _Requires: Java 11.0.23+, 17.0.11+, 21.0.3+ or 22+_ <br /> | ||
| Live Heap (v1.61.0+) | ||
| : The objects and memory allocated by each method that have not yet been garbage collected. This is useful for investigating the overall memory usage of your service and identifying potential memory leaks. The profiler automatically uses the most accurate method available for your JVM version.<br /> |
Contributor
There was a problem hiding this comment.
Suggested change
| : The objects and memory allocated by each method that have not yet been garbage collected. This is useful for investigating the overall memory usage of your service and identifying potential memory leaks. The profiler automatically uses the most accurate method available for your JVM version.<br /> | |
| : The objects and memory allocated by each method that have not yet been garbage collected. This is useful for investigating the overall memory usage of your service and identifying potential memory leaks. The profiler automatically uses the most accurate engine available for your JVM version.<br /> |
Contributor
There was a problem hiding this comment.
Optional suggestion for consistency — it looks like engine is what's used for this on java.md. Feel free to ignore this if it's important to use method here.
| | `DD_PROFILING_DDPROF_WALL_ENABLED` | `-Ddd.profiling.ddprof.wall.enabled` | Enable wallclock profiling (default: true since v1.7.0) | | ||
| | `DD_PROFILING_DDPROF_ALLOC_ENABLED` | `-Ddd.profiling.ddprof.alloc.enabled` | Enable allocation profiling with the Datadog engine | | ||
| | `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` | `-Ddd.profiling.ddprof.liveheap.enabled` | Enable live heap profiling (requires JDK 11.0.23+, 17.0.11+, 21.0.3+, or 22+) | | ||
| | `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` | `-Ddd.profiling.ddprof.liveheap.enabled` | Override for the Datadog native engine live heap implementation only; does not affect the JFR fallback (default: enabled on JDK 11+ when safe, requires `DD_PROFILING_HEAP_ENABLED=true`) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` | `-Ddd.profiling.ddprof.liveheap.enabled` | Override for the Datadog native engine live heap implementation only; does not affect the JFR fallback (default: enabled on JDK 11+ when safe, requires `DD_PROFILING_HEAP_ENABLED=true`) | | |
| | `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` | `-Ddd.profiling.ddprof.liveheap.enabled` | Override for the Datadog native engine live heap implementation only; does not affect the JFR fallback (default: enabled on supported JDK versions (11.0.23+, 17.0.11+, 21.0.3+, or 22+), requires DD_PROFILING_HEAP_ENABLED=true`) | |
Contributor
There was a problem hiding this comment.
Minor suggestion as "when safe" is a bit vague. Feel free to make adjustments if this suggestion is inaccurate.
|
|
||
| The following settings allow fine-grained control over the profiler engines. These are typically not needed for standard use cases. For detailed information about each profiler type, see the corresponding sections above: [CPU profiling](#cpu-profiling), [Wallclock](#wallclock), [Allocation profiling](#allocation-profiling), and [Live heap profiling](#live-heap-profiling). | ||
|
|
||
| **Note**: `DD_PROFILING_HEAP_ENABLED` / `-Ddd.profiling.heap.enabled` is the main toggle for all live heap profiling. When set to `false`, it disables both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback. `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` is a Datadog-engine-specific override that only controls the native implementation; the JFR fallback is unaffected by it. |
Contributor
There was a problem hiding this comment.
Suggested change
| **Note**: `DD_PROFILING_HEAP_ENABLED` / `-Ddd.profiling.heap.enabled` is the main toggle for all live heap profiling. When set to `false`, it disables both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback. `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` is a Datadog-engine-specific override that only controls the native implementation; the JFR fallback is unaffected by it. | |
| **Note**: | |
| - `DD_PROFILING_HEAP_ENABLED` controls all live heap profiling. Setting it to `false` disables both the Datadog native engine and the JFR `jdk.OldObjectSample` fallback. | |
| - `DD_PROFILING_DDPROF_LIVEHEAP_ENABLED` only controls the Datadog native engine. The JFR fallback is unaffected by this setting. |
Contributor
There was a problem hiding this comment.
Minor suggestion to make this a bit more scannable. Since the information for DD_PROFILING_DDPROF_LIVEHEAP_ENABLED shows only the environment variable syntax, I removed the system property syntax from the first note — but happy to make further adjustments if it's important to list both.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
Marks Java live heap profiling as GA (available since dd-trace-java 1.61.0).
Key changes:
profile_types.md— the profiler automatically selects the best available engine, so users don't need to know about the internal dichotomyprofiler_troubleshooting/java.md: merges the "Live heap profiling" (Datadog engine) and "Heap profiling" (JFR/OldObjectSample) sections into one, flips the configuration table from enable to disable (feature is now on by default), and adds a legacy note forDD_PROFILING_HEAP_ENABLEDMerge readiness:
AI assistance
Written with Claude Code (Claude Sonnet 4.6).
Additional notes
Relates to dd-trace-java 1.61.0 release.