|
2 | 2 |
|
3 | 3 | # Native-memory profiler exclusion |
4 | 4 |
|
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. |
8 | 9 |
|
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). |
14 | 13 |
|
15 | 14 | ## Decision |
16 | 15 |
|
@@ -92,7 +91,7 @@ A Java native-memory request means `nativemem` is enabled by the parsed argument |
92 | 91 | `nativemem=0` is a request to record every allocation; it is not a disable value. |
93 | 92 | A request without native-memory profiling must not invoke this check. |
94 | 93 |
|
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 |
96 | 95 | change the process allocator or disable ddprof. |
97 | 96 |
|
98 | 97 | ## Admission semantics |
@@ -133,7 +132,7 @@ neutral and also run on non-Linux; there only foreign-written inconsistent |
133 | 132 | own-slot states can newly reject, since the owner classifier always returns |
134 | 133 | `NOT_RECOGNIZED`. |
135 | 134 |
|
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 |
137 | 136 | Java's own current and effective forwarding targets. It is not a consistency |
138 | 137 | audit of all loaded libraries. |
139 | 138 |
|
@@ -167,9 +166,9 @@ or a different image. Renamed and extracted libraries must use the same rules. |
167 | 166 | | `NOT_RECOGNIZED` | Valid owner metadata contains no owned externally visible definition of either marker name | Continue checking other targets | |
168 | 167 | | `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 | |
169 | 168 |
|
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. |
173 | 172 |
|
174 | 173 | A recognized ddprof target takes precedence over an indeterminate target. The |
175 | 174 | 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 |
295 | 294 |
|
296 | 295 | Query the ELF GNU/SysV symbol hash/index for the two names; do not linearly scan |
297 | 296 | 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 |
299 | 298 | repeated full-library scan for each operation; account for the existing address |
300 | 299 | lookup's cold path rather than claiming it is constant time. |
301 | 300 |
|
@@ -386,26 +385,21 @@ Review must explicitly accept: |
386 | 385 | custom hooks. |
387 | 386 | 4. Startup inspection cost, with no allocation/free-path compatibility work. |
388 | 387 |
|
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. |
393 | 392 |
|
394 | 393 | ## Sources and verification baseline |
395 | 394 |
|
396 | 395 | The mechanism and lifecycle distinctions above were checked against released |
397 | 396 | java-profiler 1.52.1, ddprof 0.26.0/0.27.0, and zstd-jni 1.5.7-25 on Linux x86_64 |
398 | 397 | with glibc 2.39 and jemalloc 5.3.0. There are 58 checked cases covering routing, |
399 | 398 | 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 |
409 | 403 | establish behavior for that architecture or mode. No service-specific |
410 | 404 | percentages, production growth rates, or RSS measurements are assumed here. |
411 | 405 |
|
|
0 commit comments