Skip to main content

​
What is ap-query?

ap-query is a command-line tool for analyzing async-profiler JFR (Java Flight Recorder) recordings and profiling data. It transforms raw profiling data into actionable insights through a suite of analysis commands designed for efficient, token-aware workflows.
ap-query is built for coding agents (Claude Code, Codex, etc.), not human-first interactive profiling workflows. It prioritizes compact, parseable output that helps agents identify performance issues without burning tokens or polluting context.

​
Why ap-query exists

Raw profiling data overwhelms LLM agents. They burn tokens parsing massive stack traces, pollute their context with irrelevant data, and still miss critical hotspots. ap-query solves this by providing:
  • Compact output: Plain text summaries that agents can parse efficiently
  • Targeted queries: Commands that answer specific questions (“what’s hot?”, “who calls this?”, “what changed?”)
  • Smart defaults: Automatic event selection, idle filtering, and threshold-based reporting
  • Agent-first design: No interactive prompts, no JSON bloat, just actionable terminal output

​
Key features

Hotspot triage

Identify performance bottlenecks instantly with ap-query hot and ap-query info commands that rank methods by self-time and total-time.

Call tree analysis

Drill down into specific methods with ap-query tree and ap-query callers to understand calling patterns and attribution.

Time-based analysis

Analyze specific time windows in JFR recordings with --from and --to flags, or visualize performance over time with ap-query timeline.

Performance regression detection

Compare two profiles or time windows with ap-query diff to identify regressions, improvements, and new hotspots.

Multiple input formats

Supports JFR binary files (.jfr, .jfr.gz), pprof protobuf (.pb.gz, .pprof), and collapsed stack text format.

Event type support

Analyze CPU profiling, wall-clock time, heap allocations, lock contention, and hardware performance counters.

​
Built for agents

ap-query includes an agent skill system that teaches coding agents how to profile and analyze JVM applications: 
# Install the agent skill for Claude Code or Codex
ap-query init
Once installed, agents automatically know how to:
  • Profile Java applications with async-profiler
  • Analyze recordings with ap-query commands
  • Interpret results and suggest concrete optimizations
  • Drill down into hotspots with the right commands
The skill embeds the exact paths to asprof and ap-query on your system, so agents can invoke profiling workflows without fumbling with PATH or installation details.

​
Example workflow

Here’s what a typical agent-driven profiling session looks like:
1

Profile the application

The agent runs async-profiler to capture a 30-second CPU profile:
asprof -d 30 -f profile.jfr <pid>
2

Triage with info

Quick overview of events, threads, and hot methods:
ap-query info profile.jfr
3

Drill down into hotspots

Investigate the top method with tree and callers:
ap-query tree profile.jfr -m HashMap.resize --depth 6
ap-query callers profile.jfr -m HashMap.resize
4

Report findings

The agent synthesizes findings into concrete next actions: “60% CPU in HashMap.resize due to excessive map growth; consider pre-sizing maps or using alternative data structures.”

​
Next steps

Installation

Install ap-query and set up agent integration

Quickstart

Profile your first application and run your first analysis

Command Reference

Explore all available analysis commands

Agent Integration

Deep dive into agent skill installation and usage

Build docs developers (and LLMs) love

Get started for freeTalk to us