Skip to content

Commit 316e037

Browse files
committed
Document native-memory admission as implemented
1 parent 54f26e1 commit 316e037

3 files changed

Lines changed: 23 additions & 29 deletions

File tree

‎ddprof-lib/src/main/cpp/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ before working on a subsystem.
1717
| Profiling engines (CPU, wall-clock, allocation, native memory, liveness; allocation/liveness stack capture via `allocstack`, with JVMTI retry for unsafe frames, depth-limit truncation and separate verification scratch) | [doc/architecture/ProfilingEngines.md](/doc/architecture/ProfilingEngines.md) |
1818
| JFR integration (FlightRecorder, metadata, constant pools, buffers) | [doc/architecture/JfrIntegration.md](/doc/architecture/JfrIntegration.md) |
1919
| Live-heap reference chains (implementation, leak-signal gate, scheduling, design) | [doc/architecture/LiveHeapReferenceChainsImplementation.md](/doc/architecture/LiveHeapReferenceChainsImplementation.md), [doc/architecture/ReferenceChainsSignalsExplained.md](/doc/architecture/ReferenceChainsSignalsExplained.md), [doc/ReferenceChainsDesign.md](/doc/ReferenceChainsDesign.md), [doc/ReferenceChainsCollectionSummary.md](/doc/ReferenceChainsCollectionSummary.md) |
20-
| Native memory profiling (malloc interception installed per recording and restored on stop, sampling) | [doc/architecture/NativeMemoryProfiling.md](/doc/architecture/NativeMemoryProfiling.md) |
20+
| Native memory profiling (malloc interception installed per recording and restored on stop; startup admission check for conflicting native-memory profilers; sampling) | [doc/architecture/NativeMemoryProfiling.md](/doc/architecture/NativeMemoryProfiling.md) |
2121
| glibc malloc arena warning (lock-free arena walk, per-chunk rule, `MallocArenaWarning`/`MallocArenaStats` events, `arenawarn`) | [doc/architecture/MallocArenaWarning.md](/doc/architecture/MallocArenaWarning.md) |
2222
| Startup sanity checks | [doc/architecture/SanityChecks.md](/doc/architecture/SanityChecks.md) |
2323
| SIGSEGV-safe library patching | [doc/architecture/SigsegvPatching.md](/doc/architecture/SigsegvPatching.md) |

‎doc/NativeMemoryProfilerExclusionDesign.md‎

Lines changed: 21 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,14 @@
22

33
# Native-memory profiler exclusion
44

5-
**Status:** Proposed; implementation authorized and in progress. The behavior
6-
described here is not yet verified: the design is being implemented and each
7-
claim below becomes verified only through its acceptance tests.
5+
**Status:** Implemented. The admission check described here ships in this
6+
change set; the glibc Linux behavior is covered by the gtest and child-JVM
7+
suites in this repository. Verification against released ddprof archives (the
8+
matrix below) is not complete for every cell.
89

9-
This document specifies a startup admission check for java-profiler native-memory
10-
profiling. It does not yet describe verified implemented behavior. The current
11-
implemented runtime contract remains
12-
[Native Memory Profiling](architecture/NativeMemoryProfiling.md) until
13-
acceptance verification is complete.
10+
This document records the design decision and its rationale. The implemented
11+
runtime contract is documented in
12+
[Native Memory Profiling](architecture/NativeMemoryProfiling.md).
1413

1514
## Decision
1615

@@ -92,7 +91,7 @@ A Java native-memory request means `nativemem` is enabled by the parsed argument
9291
`nativemem=0` is a request to record every allocation; it is not a disable value.
9392
A request without native-memory profiling must not invoke this check.
9493

95-
No new configuration flag or override is proposed. The check must not silently
94+
No new configuration flag or override is added. The check must not silently
9695
change the process allocator or disable ddprof.
9796

9897
## Admission semantics
@@ -133,7 +132,7 @@ neutral and also run on non-Linux; there only foreign-written inconsistent
133132
own-slot states can newly reject, since the owner classifier always returns
134133
`NOT_RECOGNIZED`.
135134

136-
Do not inspect every application's allocator import. The proposed check covers
135+
Do not inspect every application's allocator import. The check covers
137136
Java's own current and effective forwarding targets. It is not a consistency
138137
audit of all loaded libraries.
139138

@@ -167,9 +166,9 @@ or a different image. Renamed and extracted libraries must use the same rules.
167166
| `NOT_RECOGNIZED` | Valid owner metadata contains no owned externally visible definition of either marker name | Continue checking other targets |
168167
| `INDETERMINATE` | Owner/lifetime/metadata cannot be validated, owned marker definitions are partial, wrong-kind or ambiguous, or forwarding state is inconsistent | Reject with an inspection diagnostic |
169168

170-
**Proposed conservative policy:** indeterminate inspection declines Java
171-
native-memory profiling. This is a review decision, not an existing behavior.
172-
Do not report that ddprof was detected when inspection was indeterminate.
169+
**Conservative policy:** indeterminate inspection declines Java
170+
native-memory profiling. Do not report that ddprof was detected when inspection
171+
was indeterminate.
173172

174173
A recognized ddprof target takes precedence over an indeterminate target. The
175174
check may stop on `DDPROF`; otherwise retain any indeterminate result and inspect
@@ -295,7 +294,7 @@ An inspection failure must become `INDETERMINATE`, not a false negative or crash
295294

296295
Query the ELF GNU/SysV symbol hash/index for the two names; do not linearly scan
297296
large symbol tables. The existing `CodeCache::findSymbol()` uses a linear name
298-
scan [S6] and is not the proposed production lookup. Likewise, do not add a
297+
scan [S6] and is not the production lookup. Likewise, do not add a
299298
repeated full-library scan for each operation; account for the existing address
300299
lookup's cold path rather than claiming it is constant time.
301300

@@ -386,26 +385,21 @@ Review must explicitly accept:
386385
custom hooks.
387386
4. Startup inspection cost, with no allocation/free-path compatibility work.
388387

389-
While the implementation is in progress, do not present this proposal as the
390-
current runtime contract. When the behavior is implemented and verified,
391-
update the native-memory architecture page, its AGENTS subsystem summary, and
392-
relevant operational guidance in the same change set.
388+
The implemented runtime contract is documented in
389+
[Native Memory Profiling](architecture/NativeMemoryProfiling.md), and the
390+
native subsystem summary in `ddprof-lib/src/main/cpp/AGENTS.md` names the
391+
admission check. Keep both in sync with this design in the same change set.
393392

394393
## Sources and verification baseline
395394

396395
The mechanism and lifecycle distinctions above were checked against released
397396
java-profiler 1.52.1, ddprof 0.26.0/0.27.0, and zstd-jni 1.5.7-25 on Linux x86_64
398397
with glibc 2.39 and jemalloc 5.3.0. There are 58 checked cases covering routing,
399398
owner identity, recording lifecycle, later activation, and closed-stream live
400-
accounting. The implementation is in progress; acceptance verification is not
401-
complete.
402-
403-
The allocation-hook source is identical between the released Java version and
404-
main `399ce5e60b9543940ebed4f4769474f05ae37d79`. ddprof ELF hook handling is identical
405-
between those releases and main `9830a2e27ac15fa08f4761c94392de8b9edb3d04`. These
406-
main revisions were source-reviewed, not built and executed. The implementation
407-
verification matrix targets Linux x86_64 and aarch64 with glibc, using the
408-
published ddprof 0.26.0 and 0.27.0 archives. A blocked matrix cell does not
399+
accounting. The glibc Linux behavior is covered by the gtest and child-JVM
400+
suites in this repository; the implementation verification matrix targets Linux
401+
x86_64 and aarch64 with the published ddprof 0.26.0 and 0.27.0 archives and is
402+
not complete for every cell. A blocked matrix cell does not
409403
establish behavior for that architecture or mode. No service-specific
410404
percentages, production growth rates, or RSS measurements are assumed here.
411405

‎doc/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ All documentation files use **PascalCase** naming (e.g., `BuildSystemGuide.md`).
5353
### Design
5454

5555
- [BitsReviewMergeGateDesign](BitsReviewMergeGateDesign.md) - Bits PASS merge gate: policy, implementation, trusted status publisher, and enforcement proposal pending separate approval
56-
- [NativeMemoryProfilerExclusionDesign](NativeMemoryProfilerExclusionDesign.md) - Proposed admission check for conflicting native-memory profilers and its lifecycle limits
56+
- [NativeMemoryProfilerExclusionDesign](NativeMemoryProfilerExclusionDesign.md) - Admission check design for conflicting native-memory profilers: decision, rationale and lifecycle limits
5757
- [ReferenceChainsCollectionSummary](ReferenceChainsCollectionSummary.md) - Short reference-chain overview and limits
5858
- [ReferenceChainsDesign](ReferenceChainsDesign.md) - Reference-chain design decision and trade-offs
5959
- [WorkTracking](WorkTracking.md) - Work-tracking phases: Intent, Design, Build and Test, Deploy

0 commit comments

Comments
 (0)