github/awesome-copilot / skills/java-diagnostics
java-diagnostics
VerifiedSymptom-first runtime diagnostics for JVM applications using JDK tools: jcmd, jstack, jmap, jstat, JFR, GC logs, async-profiler, Native Memory Tracking, and Eclipse MAT. Use when a Java app has high CPU, memory leaks or OutOfMemoryError, slow startup, deadlocks or thread starvation, long GC pauses, native memory growth, or slow requests. Includes permission tiers for safe use.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| references/async-profiler.md | markdown | 3.0 KB |
| references/containers.md | markdown | 1.7 KB |
| references/gc.md | markdown | 1.6 KB |
| references/heap.md | markdown | 3.0 KB |
| references/jcmd-basics.md | markdown | 1.9 KB |
| references/jfr.md | markdown | 2.3 KB |
| references/native-memory.md | markdown | 1.5 KB |
| references/thread-dumps.md | markdown | 3.3 KB |
references/heap.md
View on GitHub# Heap, histograms, Eclipse MAT
## Tier 2: class histogram (no full GC with `-all=true`, but still a safepoint pause)
```bash
jcmd <pid> GC.class_histogram -all=true | head -40 # no GC; includes unreachable objects
jmap -histo <pid> | head -40 # no GC
jcmd <pid> GC.class_histogram | head -40 # full GC, live objects only
jmap -histo:live <pid> | head -40 # full GC, live objects only
```
All four run heap inspection at a safepoint, which can pause application threads for the duration of the scan on a large heap: on production, get explicit consent and state the overhead first. The last two also force a full GC. The first two avoid the full GC but may count garbage that is not yet collected. Take two histograms several minutes apart under load; classes whose instance count and bytes keep growing are leak suspects.
## Tier 3: heap dump (explicit consent required)
Before running: state the target path, check free disk (`df -h`; roughly the used heap size), and warn of a stop-the-world pause proportional to heap size. Write to a restricted directory (`chmod 700`).
```bash
jcmd <pid> GC.heap_dump /secure/dir/heap.hprof # live objects only (full GC)
jcmd <pid> GC.heap_dump -all=true /secure/dir/heap.hprof # include unreachable objects
```
`jmap -dump:live,format=b,file=heap.hprof <pid>` is the older equivalent. The file is written by the target JVM, so the path must be writable by it (and inside the container if containerized).
**Sensitive data**: a heap dump contains everything in memory: credentials, tokens, session data, personal data. Never upload or share it (including with AI services or issue trackers). Redaction is not a reliable safeguard. Analyze locally and securely delete the file when done.
Automatic dump on OOM (an opt-in startup flag, still Tier 3 because of the data and disk usage):
```
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/secure/dir/
```
Set `HeapDumpPath` to a volume with enough space; in containers an unbounded dump can fill the node.
## Analyze with Eclipse MAT
1. Install Eclipse Memory Analyzer (https://eclipse.dev/mat/) from the official download page. It needs a Java runtime and a heap of about 1.5x the dump size (edit `MemoryAnalyzer.ini`, `-Xmx`).
2. Open the `.hprof`; run the **Leak Suspects** report first.
3. Use the **Dominator Tree** (sorted by retained heap) to find what holds memory.
4. For a suspect object, **Path to GC Roots, excluding weak/soft references** shows why it is not collected.
5. Compare two dumps with the histogram comparison to confirm growth.
6. Common causes: unbounded caches or maps, static collections, listeners never removed, ThreadLocals in pooled threads, classloader leaks on redeploy, large result sets.
Headless parsing is available through `ParseHeapDump.sh` in the MAT distribution (`-vmargs -Xmx...`), producing report ZIPs.
## Alternative (Tier 2)
JFR with `jdk.OldObjectSample` and path-to-gc-roots (`path-to-gc-roots=true`) finds leak candidates without a full dump; see [jfr](jfr.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |