Async Profiler

async-profiler

Low-overhead sampling profiler for JVMs (HotSpot, OpenJ9, GraalVM CE) that combines AsyncGetCallTrace with perf_events to produce accurate stack traces — including Java, JIT-inlined, native, and kernel frames.

The body below is the workflow. Detailed knowledge lives in references/ and is loaded only when needed.

Workflow

1. Identify the JVM — jps -v, jcmd, or pgrep -f java in a container. Confirm the workload has reached steady state; profiles taken during JIT warmup are dominated by C2 CompilerThread and don't reflect real hot paths.

1. Pick the event based on the symptom. If the user gave a symptom but not the event, choose for them and explain the choice. See references/events.md for the full list including hardware counters.

| Symptom | Event | | --- | --- | | High CPU, slow throughput | cpu | | Low CPU but slow latency | wall (samples threads in any state) | | Frequent young GC, GC pressure | alloc | | Thread dump full of BLOCKED/WAITING | lock | | Memory-bound suspicion (large data scans) | hardware cache-misses | | GC pauses longer than expected | --ttsp (time-to-safepoint) | | Container without perf permissions | itimer (fallback) |

1. Pick the attach mode. See references/attach-modes.md for full details.

• PID attach — running JVM, ad-hoc: asprof -d 30 -f cpu.html
• -agentpath — captures startup; needed when -XX:+DisableAttachMechanism is set
• Programmatic API — embed in tests, expose via internal HTTP endpoint

1. Pick the duration. 30–120s ad-hoc; for production use rotating JFR (scripts/continuous-jfr.sh). Long enough to capture steady-state behavior; short enough to keep file size manageable.

1. Capture as JFR when possible, render flame graphs from it. JFR is re-renderable — you can re-filter by thread, exclude packages, or diff against another recording without re-profiling. Pure HTML output is frozen.

1. Analyze the flame graph. Width = samples (not time). Wide plateaus near the top are direct hotspots. Wide trunks at the bottom are entry frames — drill upward to find your code. See references/flame-graphs.md for color semantics, search, and reading patterns.

1. Verify the change. After modifying code, re-profile under the same workload (same RPS, same input) and run jfrconv --diff baseline.jfr current.jfr diff.html. Blue frames in changed code paths confirm improvement; red signals regression.

Quick command reference

| Goal | Command | | --- | --- | | 30s CPU flame graph | asprof -d 30 -f cpu.html | | Allocation profile | asprof -e alloc -d 60 -f alloc.html | | Lock contention | asprof -e lock --lock 1ms -d 60 -f lock.html | | Wall-clock (off-CPU visible) | asprof -e wall -t -d 60 -f wall.html | | Time-to-safepoint | asprof --ttsp -d 60 -f ttsp.html | | Continuous start/stop | asprof start -e cpu ... asprof stop -f out.jfr | | List events for a PID | asprof list | | Convert JFR to flame graph | jfrconv --cpu profile.jfr profile.html | | Differential flame graph | jfrconv --diff baseline.jfr current.jfr diff.html |

Helper scripts

Located in scripts/. Read a script before suggesting it; each encodes safe defaults.

| Script | Purpose | | --- | --- | | scripts/install.sh | Download and install latest async-profiler for the current platform | | scripts/attach.sh [event] [seconds] | One-shot attach and flame graph | | scripts/continuous-jfr.sh [rotate] [dir] | Rotating JFR for production with hostname/PID-tagged output | | scripts/diff-profiles.sh [out] | Differential flame graph wrapping jfrconv --diff |

References

Read on demand. Each file is self-contained.

| File | When to read | | --- | --- | | references/events.md | Picking the right event; full list including hardware counters and method-tracing | | references/attach-modes.md | Choosing PID-attach, -agentpath, programmatic API, or jcmd integration | | references/flags.md | Complete CLI flag reference with examples | | references/output-formats.md | flamegraph / jfr / collapsed / pprof / tree — when to use each | | references/flame-graphs.md | Reading flame graphs: color semantics, search, differential, gotchas | | references/jfr.md | JFR analysis with jfrconv, JMC, IntelliJ Profiler, Jeffrey | | references/pitfalls.md | Inlining, container limits, kernel perms, sampling skew, virtual threads | | references/platform-notes.md | Linux vs macOS vs Docker vs Kubernetes vs cloud (Lambda, Cloud Run) | | references/workflows.md | End-to-end scenarios — latency spike, alloc churn, deadlock, GC, A/B compare | | references/api.md | Programmatic Java API; embedding in tests and health endpoints | | references/integration.md | JMH, Spring Boot, Quarkus, Pyroscope, Parca, IntelliJ, Datadog |

Output format

When reporting profile findings to the user:

• State the question first — "You asked about X; here's what the profile shows."
• Show the top frame(s) with sample share — "com.acme.Foo.bar is 42% of CPU samples."
• Explain why it's hot, not just that it is — "It builds a regex on every call; cache the compiled Pattern."
• Recommend a concrete next step — code change, follow-up profile with a different event, or diff after the fix.
• Link the artifact — full path to the .html or .jfr file so the user can open it.

Avoid dumping full flame graph trees as text; the visual artifact is the deliverable.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: umit
• Source: umit/skills
• License: MIT
• Homepage: https://umitunal.net/

Install and usage instructions live in the source repository linked above.