Skip to content

github/awesome-copilot / skills/java-diagnostics

java-diagnostics

Verified

Symptom-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.

FileKindSize
SKILL.mdskill md7.2 KB
references/async-profiler.mdmarkdown3.0 KB
references/containers.mdmarkdown1.7 KB
references/gc.mdmarkdown1.6 KB
references/heap.mdmarkdown3.0 KB
references/jcmd-basics.mdmarkdown1.9 KB
references/jfr.mdmarkdown2.3 KB
references/native-memory.mdmarkdown1.5 KB
references/thread-dumps.mdmarkdown3.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).
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall