Skip to content

profiler-cli: document the marker field:value search syntax #6265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fqueze merged 2 commits into from
Aug 18, 2026
+44 −6
Merged

profiler-cli: document the marker field:value search syntax #6265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e84c5d0
profiler-cli: document the marker field:value search syntax
fqueze Aug 18, 2026
8beddab
Merge branch 'main' into profiler-cli-search-syntax-docs-pr
fqueze Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion profiler-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ profiler-cli thread info --thread t-0 # View info for specific thread witho
| Flag | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--thread <handle>` | Specify thread (e.g., `t-0`) |
| `--search <term>` | Filter results by substring. For samples commands, comma-separates multiple terms that all must match (AND); `\|` is literal, not OR. |
| `--search <term>` | Filter by substring; `thread markers` also takes `field:value` (see its `--help`). |
| `--include-idle` | Include idle samples (excluded by default in samples commands) |
| `--json` | Output as JSON (for use with `jq`, etc.) |
| `--limit <N>` | Limit number of results shown |
Expand Down
17 changes: 13 additions & 4 deletions profiler-cli/guide.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,12 +67,20 @@ CORE WORKFLOW
Step 5: Analyze markers (browser events, timers, etc.)
profiler-cli thread markers All markers with aggregated stats
profiler-cli thread markers --category Layout Filter by category
profiler-cli thread markers --search DOMEvent Filter by name substring
profiler-cli thread markers --search DOMEvent Filter by substring in name OR payload
profiler-cli thread markers --search name:DOMEvent Narrow to one field ("field:value")
profiler-cli thread markers --min-duration 10 Only markers >= 10ms
profiler-cli thread markers --has-stack Only markers with stack traces
profiler-cli thread markers --list Flat chronological list (one row per marker)
profiler-cli thread markers --search X --list List all individual X markers with handles

--search on "thread markers": a bare term matches the marker name, category, payload
type AND all payload values; "field:value" narrows to one field; "-field:value"
excludes; comma separates (positives OR'd, then exclusions). "field" is the payload
key from "marker info --json" fields[].key, not the printed label. Caveat: "name" is
also a payload key on Text markers, so "name:" is not name-only. Details:
"thread markers --help".

profiler-cli thread network Top 20 requests (slowest first) with timing phases
profiler-cli thread network --sort start Chronological order instead of slowest-first
profiler-cli thread network --limit 0 All requests (no limit)
Expand Down Expand Up @@ -393,9 +401,10 @@ TIPS
- Idle time alone is not a finding: only investigate idle during a period when the
thread should be busy (e.g. inside a zoom on a jank marker), which may indicate
lock contention or blocking on another thread
- --search has no OR operator. "|" and "\|" are literal characters that will match
nothing. "--search foo,bar" is AND (both must appear). To get OR behavior, run two
separate commands: once with "--search foo", once with "--search bar".
- On samples commands --search has no OR operator. "|" and "\|" are literal characters
that will match nothing. "--search foo,bar" is AND (both must appear). To get OR
behavior, run two separate commands: once with "--search foo", once with "--search
bar". ("thread markers" differs: comma is OR there.)
- Try filters ephemerally first (as flags on thread commands) before committing
with "filter push"
- "filter push --during-marker --search X" is powerful for correlating CPU work
Expand Down
31 changes: 30 additions & 1 deletion profiler-cli/src/commands/thread.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,12 @@ export function registerThreadCommand(
.command('markers')
.description('List markers with aggregated statistics')
.option('--thread <handle>', 'Thread handle (e.g. t-0)')
.option('--search <term>', 'Filter by substring')
.option(
'--search <term>',
'Filter markers. A bare term matches the marker name, category, payload ' +
'type and payload field values; "field:value" narrows to one field, ' +
'"-field:value" excludes, comma separates terms (OR). See "search syntax" below'
)
.option(
'--category <name>',
'Filter by category name (case-insensitive substring match)'
Expand Down Expand Up @@ -215,6 +220,30 @@ export function registerThreadCommand(
'Number of top markers to include per group in JSON output (default: 5)'
)
.option('--list', 'Show a flat chronological list of individual markers')
.addHelpText(
'after',
`
--search syntax (as on profiler.firefox.com's marker search box):

bare term matches the marker name, category, payload type AND every
payload field value -- so "--search FAIL" also hits messages
containing "Failed"
field:value narrows to one field
-field:value excludes; a bare "-term" is NOT a negation, the "-" is literal
a,b comma separates: positives OR'd, then exclusions applied

"field" is the payload key from "marker info <handle> --json" fields[].key, not
the label that "marker info" prints (Glean: "id:abi", not "metric:abi"). An
unrecognized field is not an error -- the term is just matched literally.

"name:" is not a name-only filter: "name" is also a payload key on Text and
TextStack markers, so it matches their detail text too.

Examples:
profiler-cli thread markers --search "eventType:keydown"
profiler-cli thread markers --search "-name:CompositorScreenshot"
profiler-cli thread markers --search "name:DOMEvent,-eventType:keydown"`
)
).action(async (opts) => {
let markerFilters: MarkerFilterOptions | undefined;

Expand Down
Loading