Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/perf-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ Then read the check files that apply to the diff:

| File | Checks | Load |
|---|---|---|
| `references/checks/memory.md` | #3 unbounded memory, J5 cardinality-sensitive aggregator, J6 weak-ref strengthening, J13 large retained `byte[]` | always |
| `references/checks/allocation.md` | #1 per-call allocation, #7 escape defeated, J1 EA, J4 GC → tail latency; defensive copies, capturing lambdas, `Optional`/boxing | always |
| `references/checks/memory.md` | #3 unbounded memory, J5 cardinality-sensitive aggregator, J6 weak-ref strengthening, J13 large retained `byte[]`, J15 JVM-wide interning of parsed input | always |
| `references/checks/allocation.md` | #1 per-call allocation, #7 escape defeated, J1 EA, J4 GC → tail latency, J16 shared sentinel / shared-bytecode traversal defeats EA; defensive copies, capturing lambdas, `Optional`/boxing | always |
| `references/checks/repeat-work.md` | #2 repeat work, J8 backtracking regex; regex compile, `String.format`, `Config.get()`, Streams | always |
| `references/checks/critical-path.md` | #4 deferrable work, #6 FFI crossing, J3 JNI + virtual-thread pinning | always |
| `references/checks/collections.md` | wrong collection type, mis-sizing, concurrency choice | always |
Expand Down
35 changes: 34 additions & 1 deletion .agents/skills/perf-review/references/checks/allocation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Per-call and escaping allocation

Checks #1, #7, J1, J4. SEV-2/3, can reach SEV-1 via tail latency.
Checks #1, #7, J1, J4, J16. SEV-2/3, can reach SEV-1 via tail latency.

The tracer shares the application heap. Additional allocation contributes to GC and raises
stop-the-world pauses — directly increasing tail latency for the customer's application. The JVM's
Expand Down Expand Up @@ -31,6 +31,39 @@ escapes, and it's real.
to answer exactly this (e.g. its Javadoc says run with a GC profiler to confirm
scalar-replacement) and that benchmark has been run, treat the question as answered — list it
under Correctly suppressed / Checked, no issue instead of asking the reader to re-verify.
- **J16 — "Optimizing" a short-lived object defeats Escape Analysis** *(refines #7, J1)*. Two
changes that look like wins make escape analysis keep an object it would otherwise have removed.
Judge by the returned object's expected lifetime: these apply only to short-lived objects the
caller drops within the loop or call (iterators, cursors, small result holders, lambdas).
Sharing a long-lived object, or one that escapes anyway (stored, returned up the stack, kept), is
still a win.
- *Special-casing a path:* returning a shared sentinel (an empty iterator, a cached empty cursor
or result) on some paths and a fresh object on others. To C2 the result is a merge of "new" and
"existing", and it won't scalar-replace a merged allocation, so the fresh object becomes a real
allocation on the common path too. Fix: return a new object of the same class on every path,
the empty case included; keep any shared object out of the short-lived role.
- *Inheriting shared bytecode for a hot traversal:* an immutable collection iterated on a hot
path that inherits `AbstractList`'s or `AbstractCollection`'s iterator, `isEmpty()` or
`Iterable.forEach`. That bytecode, and its profile, is shared by every subclass in the
application, so its `size()`/`get()` calls go megamorphic, aren't inlined, and the iterator
escapes. A quiet benchmark JVM hides it; measured with the profile polluted first, an inherited
iterator cost 160 B and about 5× per walk, and `PrintInlining` showed the calls as virtual.
Fix: give the class its own iterator, `forEach` and `isEmpty`, so their calls see one class.
Mixing list classes at one call site (`emptyList`/`singletonList`/`ArrayList`) does the same
to the caller's own sites, even unpolluted.
- *Evidence to cite:* `EscapeShapeBenchmark` (internal-api JMH, `datadog.trace.util.escape`)
measures these shapes across JDKs, in bytes per op on JDK 8 / 17 / 25: `singleSite` and
`flagOnOneAllocation` 0 / 0 / 0, `mergeWithStatic` (the shared sentinel) 8 / 8 / 8,
`mergeOfTwoAllocations` 16 / 16 / 16, `backingMegamorphic` (three implementations behind one
site) 24, and `mergeWithNull` (`return ok ? new X() : null`) 8 / 8 / 0, which is still a trap
on the Java 8 the tracer supports. `Maybe` is the worked example: one construction site, the
outcome in a plain nullable field rather than a singleton, and `@NoEscape`;
`MaybeUsagePatternsBenchmark#badMultiConstructionSite` shows two construction sites costing
16 B/op.

**flag-as-measure** ("may keep an object escape analysis would remove; verify with `-prof gc`,
and with the shared profile polluted first by walking several other list classes before the trial,
as `BenchmarkUtils.warmUpHashDispatch` does for hashing") — SEV-2/3.
- **J4 — GC pressure → *tail* latency** *(refines #1)*. Hot-path allocation → more GC → STW pauses
→ app **tail** latency, not just throughput (the tracer shares the app heap). ZGC has short
pauses but isn't common — assume G1/Parallel. flag-as-measure ("may raise tail latency; verify
Expand Down
12 changes: 11 additions & 1 deletion .agents/skills/perf-review/references/checks/memory.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Memory and retention

Checks #3, J5, J6, J13. Unbounded memory is SEV-1 — flag aggressively.
Checks #3, J5, J6, J13, J15. Unbounded memory is SEV-1 — flag aggressively.

A collection that grows without a bound can kill the customer's container. The tracer shares the
application heap — there is no isolation. A false positive here is cheap insurance against a
Expand Down Expand Up @@ -38,6 +38,16 @@ container kill. Flag aggressively.
SEV-3**. Fix: `ChunkedBuffer` / `ChunkedStreamingBuffer` (APMLP-2114); off-heap isn't a fix, it
only moves the bytes to native memory. Trap: a power-of-two 512 KiB size is humongous because of
its 16-byte header, and `GrowableBuffer` rounds up to a power of two.
- **J15 — JVM-wide interning of parsed input** *(refines #3)*. `String.intern()`, or Jackson's
`JsonFactory.Feature.INTERN_FIELD_NAMES` (on by default), applied to text read from input: a
configuration, a payload, a header, a parsed document. The JVM's string table outlives the parse,
so it holds that text for the life of the process: it grows with the input's cardinality, and it
can retain customer data (targeting ids, user names) that should die with the parse. Literals and
a small closed set of names are fine; the JVM interns literals anyway.
**flag-with-confidence** when the interned text comes from input — SEV-2 for request or payload
data (unbounded cardinality), SEV-3 for configuration. Fix: share strings per parse — a per-parse
canonicalizing table dropped when the parse returns — and turn `INTERN_FIELD_NAMES` off on the
`JsonFactory`.

## Patterns

Expand Down