top-crashers

name	top-crashers
description	Get top crashers from Brave's Backtrace crash reporting. Shows crash signatures, stacks, platforms, versions, channel breakdown, code origin, and regression detection. Triggers on: top crashers, crash report, what's crashing, top crashes, crash analysis, regression crashers, new crashes.
argument-hint	[--days 7] [--platform Windows] [--compare 2] [--new-only] [--crashes-only] [--channels nightly,beta] [--brave-only]

Top Crashers

Query Brave's Backtrace crash reporting instance for top crashers. Returns developer-actionable data including crash signatures, stack traces, platform/version breakdowns, channel mapping, code origin classification, and triage URLs.

PII-safe: Only aggregate data is output. Use the triage URLs for full crash details.

---

When to Use

• Investigating stability regressions after a release
• Prioritizing crash fixes — which crashes affect the most users
• Detecting new crashers introduced by recent changes
• Filing crash bugs — the output includes suggested issue titles and labels
• During development — checking if your area of code has top crashers

---

Environment Requirements

The BACKTRACE_API_KEY environment variable must be set with a token that has query:post capability. The BACKTRACE_PROJECT environment variable should also be set (or pass --project as an argument).

If not set, inform the user:

BACKTRACE_API_KEY must be set. Create a token with query:post capability in Backtrace project settings.
BACKTRACE_PROJECT should be set to the Backtrace project name (or pass --project).

---

The Job

When invoked, run the top-crashers script and present the results to the user.

Step 1: Parse Arguments

Map the user's request to script arguments:

User says	Script flags
"top crashers" (no args)	--days 7 --limit 25
"top 10 crashers"	--limit 10
"crashers on Windows"	--platform Windows
"crashers on Mac"	--platform Darwin
"crashers on Linux"	--platform Linux
"crashers on Android"	--platform Android
"crashers in version 1.73"	--version 1.73.
"new crashers" or "crash regressions"	--new-only
"compare crashers" or "what's regressing"	--compare 2
"crashers last 30 days"	--days 30
"crashers since 2025-02-01"	--since 2025-02-01
"worst crashers"	--order count (default)
"most recent crashers"	--order last-seen
"actual crashes" or "real crashes"	--crashes-only
"crashes on nightly" or "nightly crashers"	--channels nightly
"crashes on nightly and beta"	--channels nightly,beta
"release crashes"	--channels release
"brave code crashes" or "our crashes"	--brave-only
"what should we fix" or "actionable crashes"	--crashes-only --channels nightly

If the user provides explicit flags (e.g., /top-crashers --compare 3 --platform Windows), pass them through directly.

Step 2: Run the Script

python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --format json [parsed flags]

Always use --format json when running programmatically so you can parse and present the results. For a quick human-readable dump, use --format markdown instead.

Step 3: Present Results

After running the script, present the results to the user in a clear format:

1. Summary header: "Found N crash groups in the last M days"
2. For each crasher (in order):
   • Rank, suggested title, and badges:
     • [CRASH] or [DUMP_WITHOUT_CRASHING] — whether this is an actual crash or DumpWithoutCrashing. DumpWithoutCrashing is a non-fatal diagnostic that does NOT affect users.
     • [BRAVE], [CHROMIUM], or [MIXED] — whether the crashing code is in Brave's codebase (src/brave) or upstream Chromium (src/). Only Brave code crashes are directly fixable by the Brave team.
     • [NEW], [RISING] — regression indicators
   • Crash count and rate (crashes/day)
   • Channel breakdown — which channels are affected (Nightly, Beta, Release, Older). Highlight whether the crash affects current Nightly since that represents the latest master code.
   • Top platform with % share
   • Top version with % share (displayed as "Brave X.Y.Z (Cr N)")
   • Recency (when last seen)
   • Callstack (top frames)
   • Triage URL for full details
3. If compare mode: Highlight NEW and RISING crashers prominently

Presentation priorities:

• Always clearly distinguish actual crashes from DumpWithoutCrashing
• Highlight crashes affecting Nightly (current master) — these are the most actionable
• Note code origin — crashes in Brave code are directly fixable
• When prioritizing what to fix, recommend focusing on: actual crashes (not dumps) that affect Nightly (current code) in Brave code

GitHub Formatting Rules

When mentioning a crasher's rank in GitHub issues, PR descriptions, or comments, never use #N syntax (e.g., #8). GitHub automatically converts #N into a link to issue or PR number N, which is misleading.

• Bad: "This is the #8 crasher this week" — GitHub links to issue/PR 8
• Good: "This is the No. 8 crasher this week", "This is crasher rank 8", "the 8th top crasher"

This applies to issue titles, bodies, PR descriptions, and comments — anywhere GitHub renders markdown.

Step 4: Offer Follow-Up Actions

After presenting results, suggest relevant follow-up actions:

• "Want me to look into any of these crashes in more detail?"
• "I can filter by a specific platform or version"
• "I can check if any of these are regressions with --compare"
• "I can show only actual crashes with --crashes-only"
• "I can filter by channel with --channels nightly, --channels nightly,beta, etc."
• "I can show only Brave code crashes with --brave-only"
• "I can draft GitHub issues for the top crashers"

---

Usage Examples

# Default: top 25 crashers in last 7 days
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT"

# Top 10, JSON output for parsing
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --format json --limit 10

# Real crashes only (exclude DumpWithoutCrashing)
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --crashes-only

# Crashes affecting current Nightly
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --channels nightly

# Crashes on Nightly and Beta
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --channels nightly,beta

# Brave-specific code crashes only
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --brave-only

# Actionable crashes: real crashes on Nightly in Brave code
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --crashes-only --channels nightly --brave-only

# Windows-only crashers
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --platform Windows

# Regression detection: compare last 2 days vs prior 2 days
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --compare 2

# Only new crashers (first seen within lookback window)
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --new-only

# Specific version, sorted by recency
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --version 1.73. --order last-seen

# Last 30 days, CSV for spreadsheet
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --format csv --days 30

# Dry run to see the query without executing
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --dry-run

# NDJSON for piping to jq
python3 ./brave-core-tools/scripts/top-crashers.py --project "$BACKTRACE_PROJECT" --format ndjson --limit 5 | jq .fingerprint

---

Script Details

Location: ./brave-core-tools/scripts/top-crashers.py

Output formats: markdown, json, ndjson, csv

Exit codes:

• 0: Success
• 1: Auth/config error (missing API key or project)
• 2: Network/API error
• 3: No results matching criteria

Full flag reference:

Flag	Description	Default
--project	Backtrace project name	BACKTRACE_PROJECT env
--days	Lookback window in days	7
--since	ISO date start (alternative to --days)	—
--limit	Max crash groups to return	25
--min-count	Minimum crash count threshold	10
--format	Output format	markdown
--platform	Filter by platform	—
--version	Filter by version prefix	—
--channel	Filter by channel	—
--order	Sort: count, last-seen, rate	count
--frames	Stack frames to show	8
--new-only	Only first-seen-in-window crashers	false
--crashes-only	Exclude DumpWithoutCrashing entries	false
--channels	Filter by channels (comma-separated: nightly,beta,release, or 'all')	all
--brave-only	Only crashes in Brave code	false
--brave-src	Path to src/brave for code origin grep	auto-discovered
--compare	Regression: compare N days vs prior N	—
--dry-run	Print query without executing	false
--verbose	Print timing/debug info	false

---

Output Fields Per Crash Group

Each crash group includes these allowlisted fields only (PII-safe):

• fingerprint — SHA256 group ID (safe to reference in issues)
• count / crashes_per_day — Occurrence counts
• classifier — Crash signal (e.g. dump, invalid-access, breakpoint, abort)
• crash_type — "crash" (actual user-impacting) or "dump" (DumpWithoutCrashing diagnostic)
• code_origin — "brave" (Brave-specific code), "chromium" (upstream), or "mixed"
• top_frame — First meaningful crashing function
• signature — Combined TopFrame (Classifier) on Platform Version
• callstack — Top N sanitized stack frames
• top_platform / platform_pct — Most affected platform + % share
• top_version / version_pct — Most affected version + % share
• channel_breakdown — {"nightly": N, "beta": N, "release": N, "older": N}
• top_channel — Channel with most crashes
• affects_nightly — Whether this crash appears on current Nightly
• first_seen / last_seen / recency — Timestamps
• is_new — Whether first seen within the lookback window
• triage_url — Link to Backtrace UI for full details
• suggested_title — Ready-to-use issue title
• labels — Suggested issue labels

In compare mode, also:

• regression_badge — NEW, RISING, FALLING, or STABLE
• change_factor — Ratio of recent vs baseline count
• baseline_count — Count from the baseline period

---

Version Format

Brave versions follow the format CHROMIUM_MAJOR.BRAVE_MAJOR.BRAVE_MINOR.BRAVE_PATCH:

• 145.1.87.42 = Brave 1.87.42 on Chromium 145
• Channel mapping is fetched from the Brave Release Schedule wiki at runtime

---

Limitations

• Requires BACKTRACE_API_KEY with query:post capability
• Stack frames are sanitized (paths stripped, truncated at 200 chars)
• Histograms show top 5 values; use triage URL for full breakdown
• Compare mode uses a simple 2x threshold for RISING detection
• Code origin detection greps for crashing symbols in src/brave when the directory is found, with namespace heuristic fallback
• Channel versions are fetched from the wiki with hardcoded fallback defaults