query
Evaluate jq expressions against JProfiler performance or heap datasets to filter, sort, aggregate, and drill into profiling results.
Instructions
Query a performance or heap dataset with a jq expression and return the result. The dataset is materialized lazily and cached per session. Each query is independent, there is no current object: builtins take explicit ids bound from earlier results, e.g. .instances[0].id as $id | {value: preview($id), keptAliveBy: pathToRoot($id).paths[0].path | map(.class)}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The expansionId of a row from a previous hotspots, callTree, allocation, probe.events, probe.controlObjects or threads.dumps query for the expand dataset, or the id of a biggest object from heap.biggestObjects for the retained dataset | |
| op | No | The filter operation for field: string comparisons (contains, startsWith, endsWith, equals, regexp), object fields (null, nonNull), numeric equals or a from/to range | |
| to | No | Inclusive upper bound for a numeric range filter or the end of the time window in seconds since recording start (telemetry.series, monitor.*) | |
| set | No | Optional for heap.instances, heap.sizes and heap.inspectionResult: a set value from a previous heap result, the operation runs on that object set instead of a class or the whole heap; class, packageFilter and the value filter cannot be combined, filterScript and generation still apply | |
| args | No | Arguments for parametric datasets, see the jprofiler://datasets resource or the datasets list in check_status | |
| from | No | Inclusive lower bound for a numeric range filter or the start of the time window in seconds since recording start (telemetry.series, monitor.*) | |
| line | No | Optional for telemetry.series: restrict the series to one line by name | |
| name | No | Optional for mbean.snapshots: an MBean object name, requires the snapshot argument | |
| sort | No | Optional for probe.events: the global selection and output order - 'duration' (default) keeps and returns the slowest events, 'startTime' the most recent ones | |
| text | No | Optional for probe.events and probe.controlObjects: text filter matched against the event description and all text payloads or the object name and text properties, comma-separated alternatives, matching per matchMode | |
| class | No | Required for heap.instances: the class to list instances of, a name value from heap.classes (after the first query, omitting it continues with the last used class) | |
| field | No | Optional value filter on heap.instances: a field path like customer.name or orders[].id | |
| limit | No | Optional row limit for heap.instances, javascript.origins, monitor.history and threads.list, the defaults and caps are documented per dataset in the check_status catalog | |
| scope | No | Optional for javascript.origins: 'recorded' (default) lists only the origins whose requests reached the profiled application, 'all' every origin the browser extension reported, with a recorded flag per row | |
| state | No | Optional for probe.controlObjects: 'open' (default) lists only objects still open, 'closed' only closed objects, 'all' both, 'collectedWithoutClose' (only jdbc with leak recording) connections that were garbage collected without close | |
| types | No | Optional for probe.events: event type names to include, comma-separated or as a JSON array, e.g. the type values of previous rows (open/close names or probe-specific names like 'Statement execution') | |
| value | No | The comparison value for field and op | |
| column | No | Optional for probe.eventHistogram: the measured value, 'duration' (default), 'throughput' for file/socket probes, or a numeric payload property name from probe.events rows | |
| metric | No | Optional for performance datasets of probe subsystems that record a size or token measurement (file, socket, AI): the measurement the hotspots and call tree are ranked by. 'duration' (default) measures event durations, the alternatives are listed in the probeMetrics section of check_status (e.g. write_throughput). Value properties in the result are then named by the metric unit (bytes, tokens) instead of micros. Cannot be combined with threadStatus | |
| thread | No | Optional for performance datasets: restrict the analysis to selected threads. 'all' (default) merges all threads, 'virtual' merges all virtual threads into one, an integer thread id selects a single thread - use a threadId from threads.list rows (the same ids the monitor datasets use). Cannot be combined with threadGroup | |
| dataset | Yes | The dataset to query. The jprofiler://datasets resource documents all datasets with arguments, row formats and examples, check_status lists them with availability for the current session | |
| groupBy | No | Optional for monitor.stats: the aggregation grouping, default monitors | |
| minCount | No | Optional for performance.outliers: only methods with at least this many invocations, default 10 | |
| snapshot | No | Optional for mbean.snapshots: the index of an MBean snapshot from the catalog | |
| threadId | No | Optional for monitor.history and monitor.graph: restrict to one waiting or owning thread id from monitor.stats | |
| eventType | No | Optional for monitor.history: restrict to one event type | |
| matchMode | No | Optional for probe.events and probe.controlObjects: how text is matched, default contains | |
| maxEvents | No | Optional for probe.events: page size of the global top-N selection, default 1000, max 10000 | |
| maxMicros | No | Optional for probe.events: maximum event duration in microseconds | |
| maxPoints | No | Optional for telemetry.series and monitor.timeline: number of consolidated points per line, default 120, max 500 | |
| minMicros | No | Optional for probe.events: minimum event duration in microseconds | |
| monitorId | No | Optional for monitor.history and monitor.graph: restrict to one monitor id from monitor.stats | |
| subsystem | No | The subsystem to analyze, a value from availableSubsystems in check_status (e.g. cpu, jdbc). If the session recorded a single subsystem it is used automatically | |
| telemetry | No | Required for telemetry.series: the telemetry to fetch, an id from telemetry.list (e.g. heap, cpu, threads, heap/PS Eden Space, gc/G1 Young Generation, custom/<name>, jdbc/<group>) | |
| expression | Yes | The jq expression, passed as a plain JSON string without surrounding quotes. . returns the dataset unchanged. Datasets are objects, the rows are in the hotspots, callTree, classes or biggestObjects array. Filtering, sorting, projection and aggregation belong in the expression. Examples: .hotspots | sort_by(-.percent) | .[0:10], .hotspots | map({method, percent, expansionId}) | .[0:5] (keep expansionId for drill-downs) or .hotspots | group_by(.method | split(".")[0]) | map({pkg: .[0].method, hotspots: length}) (delivered rows only, exact rollups of the complete recording come from the aggregation parameter). Project tree rows one level at a time: .callTree | map({method, micros, children: [(.children // [])[] | .method]}) - children and callers are omitted on leaves and omitted arrays cannot be iterated, and multi-step values in an object construction must be wrapped in parens: {key: (expr | filter)}. Drill down with the builtin expand(expansionId) inline: .hotspots | sort_by(-.percent) | .[0] | {method, callers: expand(.expansionId).callers}. Retained classes of a biggest object with the builtin retained(id): .biggestObjects | sort_by(-.retainedSize) | .[0] | {class, retained: retained(.id).classes}. Combined size analysis of an object set with the builtin sizes([ids]): .biggestObjects | {top: .[0:3] | map(.class), sizes: sizes([.[0:3][].id])}. References of a heap object with the builtins incoming(id)/outgoing(id): .instances[0] | {name, heldBy: incoming(.id).referrers | map(.class)}. GC root paths with pathToRoot(id) and value previews with preview(id): .instances[0] | {name, value: preview(.id), keptAliveBy: pathToRoot(.id).paths[0].path | map(.class)}. Capture the input before binding variables: . as $rows | ((map(.micros) | add) as $t | ...), wrap generators in constructions with [...]. Keep results small: project fields and slice with .[0:N]. | |
| filterPath | No | Optional with filterScript: a field path like customer.name or orders[].id, the script is evaluated on the objects the path navigates to instead of the instances of the class | |
| generation | No | Optional on heap.classes, heap.biggestObjects and heap.instances: restrict to objects allocated after (new) or before (old) the last markHeap action of the recorded session | |
| ignoreCase | No | Ignore case for string comparisons, default false | |
| inspection | No | Required for heap.inspectionResult: the inspection to run, an id from heap.inspections | |
| limitBytes | No | Optional byte budget for the result, default 24000. Larger results are truncated and marked as such | |
| maxBuckets | No | Optional for probe.eventHistogram: maximum bucket count, default 100, max 1000 - the histogram adapts its bucket size to stay below | |
| maxObjects | No | Optional for probe.controlObjects: maximum number of objects per state, default 200, max 2000 | |
| aggregation | No | Optional for performance and allocation datasets: the rollup level of the tree nodes. 'method' (default) aggregates per method, 'class' per class, 'package' per package, 'component' by Spring, JEE and JPA component class (controllers, services, repositories, empty for apps without such components). Class, package and component rollups are exact, they include everything below the row cutoffs of the method view, and they shrink huge deep trees to an overview. Drill back in with 'method' and a packageFilter | |
| groupScript | No | Required for the custom_grouping inspection: a Java script evaluated per object that returns the group key string, null skips the object. Read the jprofiler://api/heap-scripts resource for the script API before writing a script | |
| threadGroup | No | Optional for performance datasets: restrict the analysis to one thread group, a group value from threads.list rows (platform threads only, virtual threads have no groups). Cannot be combined with thread | |
| filterScript | No | Optional for heap.instances and heap.sizes: a Java script evaluated per object, keeping objects where it returns true - for predicates the value filter cannot express. Read the jprofiler://api/heap-scripts resource for the script API before writing a script | |
| minMaxMicros | No | Optional for performance.outliers: only methods whose slowest invocation took at least this many microseconds, default 10000 | |
| threadStatus | No | Optional for performance datasets: the thread state whose time is counted. 'running' (default for cpu) counts only time while the thread is scheduled by the OS, waiting on sockets, locks or other threads is not included. 'all' (default for probes) counts wall clock time in all states. 'net_io' counts time waiting on network or file I/O, the state of slow database or REST calls. 'waiting' and 'blocked' count time waiting on other threads or blocked on a monitor, for inter-thread handoff and lock contention analysis. Only 'all' and 'running' carry invocation counts for cpu. Not available for JFR probe subsystems | |
| packageFilter | No | Optional package filter to focus on classes of interest (heap datasets and performance subsystems), comma-separated or as a JSON array | |
| payloadFilter | No | Optional filter on payload descriptions (SQL statements, URLs) for probe subsystems, applied to hotspots and call trees before the row cutoffs. Each pattern keeps descriptions that contain it, case-sensitive, * and ? are literal characters (a lone * means no filter), comma-separated or as a JSON array, a pattern with a comma needs the array form | |
| controlObjectId | No | Optional for probe.events: restrict to the events of one control object, a controlObjectId from probe.controlObjects or probe.events rows | |
| minDurationMicros | No | Optional for monitor.history: minimum event duration in microseconds |