ap-query provides a comprehensive set of commands for analyzing async-profiler recordings. Each command is designed for a specific analysis task, from quick triage to deep-dive investigation.
Analysis Commands
info
One-shot triage showing events, threads, hot methods, and automatic drill-down
hot
Rank methods by self-time and total-time with dual-sorted tables
tree
Call tree descending from a method to show what it calls
trace
Hottest path from a method to leaf for finding critical paths
callers
Callers tree ascending to a method to show who calls it
threads
Thread sample distribution with optional grouping
timeline
Sample distribution over time (JFR only)
Comparison & Transformation
diff
Compare profiles to detect regressions and improvements
filter
Extract stacks matching a method pattern
collapse
Convert to collapsed-stack format for external tools
lines
Line-by-line breakdown within methods
Advanced Analysis
events
List available event types in a profile
script
Starlark scripting for custom analysis
Maintenance
init
Install agent skill for profiling automation
update
Update ap-query to the latest release
version
Show version and check for updates
Command Quick Reference
| Command | Purpose | Key Flags |
|---|---|---|
| info | One-shot triage | --expand, --top-threads, --top-methods |
| hot | Method hotspot ranking | --top, --fqn, --assert-below |
| tree | Descending call tree | -m/--method, --depth, --min-pct, --hide |
| trace | Hottest path to leaf | -m/--method (required), --min-pct, --fqn, --hide |
| callers | Ascending caller tree | -m/--method (required), --depth, --min-pct, --hide |
| threads | Thread distribution | --top, --group |
| timeline | Time-based analysis | --buckets, --resolution, --compare, -m/--method |
| diff | Profile comparison | --min-delta, --top, --fqn, --from/--to, --vs-from/--vs-to |
| filter | Stack extraction | -m/--method (required), --include-callers |
| collapse | Format conversion | N/A (uses shared flags) |
| lines | Line-level breakdown | -m/--method (required), --top, --fqn |
| events | List event types | N/A |
| script | Custom scripting | -c/--code or file path |
| init | Install agent skill | --project, --force, --claude, --codex |
| update | Update binary | --force |
| version | Show version | N/A |
Common Flags
All analysis commands support these shared flags:-e/--event- Event type:cpu,wall,alloc,lock, or hardware counter name (default:cpu)-t/--thread- Filter to threads matching substring--from- Start of time window (JFR only)--to- End of time window (JFR only)--no-idle- Remove idle leaf frames
Usage Pattern
ap-query auto-detects input format:.jfr/.jfr.gz→ JFR binary (full features).pb.gz/.pprof→ pprof protobuf (no timeline)- Other files → collapsed-stack text
-(stdin) → auto-detect
Input Format Support
| Format | Extensions | Supported Commands |
|---|---|---|
| JFR | .jfr, .jfr.gz | All commands |
| pprof | .pb.gz, .pb, .pprof | All except timeline |
| Collapsed | Any other | All except timeline |
Next Steps
Quickstart
Learn the basics of using ap-query
Profiling Workflow
See the complete analysis workflow