Skip to main content

​
Overview

The filter command searches for stacks containing a specific method and outputs them in collapsed stack format. This is useful for:
  • Isolating code paths that call a particular method
  • Creating focused profiles for specific functionality
  • Piping filtered stacks to other analysis tools

​
Usage

ap-query filter <file> -m <method> [flags]

​
Flags

​
--method
string
required
Required. Substring to match on method name. Short name or FQN matching.
​
--include-callers
boolean
default:"false"
Include caller frames (frames above the matched method). By default, only frames from the matched method to the leaf are shown.

​
Shared Flags

Common flags supported by most commands:
​
--event
string
default:"cpu"
Event type: cpu, wall, alloc, lock, or hardware counter name
​
--thread
string
Filter to threads matching substring
​
--start
duration
Start time of window (JFR only)
​
--end
duration
End time of window (JFR only)

​
Output Format

Outputs stacks in collapsed format: 
[thread];frame1;frame2;...;frameN count
  • One stack per line
  • Frames separated by semicolons
  • Optional thread name prefix in brackets
  • Sample count at the end
By default, shows frames from the matched method to the leaf. With --include-callers, shows the entire stack (root to leaf).

​
Examples

​
Basic Filtering

Find all stacks calling HashMap.resize: 
ap-query filter profile.jfr -m HashMap.resize
Output: 
HashMap.resize;HashMap.put;Map.putAll 42
HashMap.resize;HashMap.computeIfAbsent 18

​
Include Caller Context

Show full stacks including callers: 
ap-query filter profile.jfr -m HashMap.resize --include-callers
Output: 
java.lang.Thread.run;com.example.App.main;HashMap.resize;HashMap.put 42
java.lang.Thread.run;com.example.Service.process;HashMap.resize;HashMap.computeIfAbsent 18

​
Filter and Analyze

Pipe filtered stacks to hot for a focused analysis: 
ap-query filter profile.jfr -m "HttpHandler" | ap-query hot -
This shows the hottest methods within HTTP handling code.

​
Filter Specific Thread

Combine thread and method filtering: 
ap-query filter profile.jfr -m "Database.query" --thread worker

​
Filter Specific Event

Find allocation stacks involving ArrayList: 
ap-query filter profile.jfr -m ArrayList --event alloc

​
Time Window Filtering

Filter stacks from a specific time range: 
ap-query filter profile.jfr -m "Cache.get" --start 1m --end 2m

​
Pattern Matching

The -m flag performs substring matching on both short names and fully-qualified names: 
# Matches "HashMap.resize", "HashMap.put", etc.
ap-query filter profile.jfr -m HashMap

# Matches methods containing "resize"
ap-query filter profile.jfr -m resize

# Matches by package
ap-query filter profile.jfr -m "java.util"

# Matches by class and method
ap-query filter profile.jfr -m "HashMap.put"
Pattern matching is case-sensitive substring search, not regex. Use the script command with match() for regex patterns.

​
Use Cases

​
Isolate Feature Paths

Extract all stacks related to authentication: 
ap-query filter profile.jfr -m AuthService > auth-stacks.collapsed

​
Investigate Hotspot

After hot identifies an expensive method, filter to see its call paths: 
# Step 1: Find hot methods
ap-query hot profile.jfr

# Step 2: Filter for the hot method
ap-query filter profile.jfr -m ExpensiveMethod --include-callers

​
Create Focused Flamegraph

Generate a flamegraph for specific functionality: 
ap-query filter profile.jfr -m "Serialization" | \
  flamegraph.pl > serialization.svg

​
Compare Filtered Profiles

Compare how a specific method performs in two runs: 
ap-query filter before.jfr -m "CacheImpl" > before-cache.collapsed
ap-query filter after.jfr -m "CacheImpl" > after-cache.collapsed
ap-query diff before-cache.collapsed after-cache.collapsed

​
Debug Missing Matches

If no stacks match, verify the method exists: 
ap-query hot profile.jfr | grep -i "method-name"

​
Empty Results

If no stacks match, you’ll see: 
no samples (empty profile or all filtered out)
Common reasons:
  • Method name typo or case mismatch
  • Method not present in the selected event type (try --event wall or --event alloc)
  • Method filtered out by --thread or time window
  • Method exists but was not sampled (not in hot path)

​
Tips

Partial matches: Use partial method names to catch variations. For example, -m Logger matches Logger.info, Logger.debug, etc.
Include callers for context: Use --include-callers when you need to understand who calls the method. Omit it for cleaner output focused on the method’s own call tree.
Pipe to hot: After filtering, pipe to ap-query hot - to get a ranked list of methods within the filtered stacks.

​
See Also

  • hot - View hottest methods in a profile
  • callers - Show methods that call into a specific method
  • collapse - Convert profiles to collapsed format without filtering
  • script - Use Profile.filter() for complex filtering logic

Build docs developers (and LLMs) love

Get started for freeTalk to us