From e84c5d0b5155c4f90728a89fbacf96a05e6a59f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Qu=C3=A8ze?= Date: Tue, 18 Aug 2026 10:23:41 +0200 Subject: [PATCH] profiler-cli: document the marker field:value search syntax Document field:value, name: and - negation in `thread markers --help` and `guide`, and correct guide's "Filter by name substring", which was wrong in both directions: a bare --search term also matches payload text, while the name: prefix that narrows to the name went unmentioned. Note name: is not a name-only filter -- "name" is also a schema-declared payload key on Text/TextStack markers, so name:X tests both. --- profiler-cli/README.md | 2 +- profiler-cli/guide.txt | 17 ++++++++++++---- profiler-cli/src/commands/thread.ts | 31 ++++++++++++++++++++++++++++- 3 files changed, 44 insertions(+), 6 deletions(-) diff --git a/profiler-cli/README.md b/profiler-cli/README.md index 8d367ffd61..77787f40c1 100644 --- a/profiler-cli/README.md +++ b/profiler-cli/README.md @@ -84,7 +84,7 @@ profiler-cli thread info --thread t-0 # View info for specific thread witho | Flag | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--thread ` | Specify thread (e.g., `t-0`) | -| `--search ` | Filter results by substring. For samples commands, comma-separates multiple terms that all must match (AND); `\|` is literal, not OR. | +| `--search ` | 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 ` | Limit number of results shown | diff --git a/profiler-cli/guide.txt b/profiler-cli/guide.txt index b472c6cabd..4b401645db 100644 --- a/profiler-cli/guide.txt +++ b/profiler-cli/guide.txt @@ -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) @@ -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 diff --git a/profiler-cli/src/commands/thread.ts b/profiler-cli/src/commands/thread.ts index 0bbf432e31..85882f02e7 100644 --- a/profiler-cli/src/commands/thread.ts +++ b/profiler-cli/src/commands/thread.ts @@ -187,7 +187,12 @@ export function registerThreadCommand( .command('markers') .description('List markers with aggregated statistics') .option('--thread ', 'Thread handle (e.g. t-0)') - .option('--search ', 'Filter by substring') + .option( + '--search ', + '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 ', 'Filter by category name (case-insensitive substring match)' @@ -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 --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;