top-crashers

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:

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

Step 2: Run the Script

python3 ./.claude/skills/top-crashers/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 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT"

# Top 10, JSON output for parsing
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --format json --limit 10

# Real crashes only (exclude DumpWithoutCrashing)
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --crashes-only

# Crashes affecting current Nightly
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --channels nightly

# Crashes on Nightly and Beta
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --channels nightly,beta

# Brave-specific code crashes only
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --brave-only

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

# Windows-only crashers
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --platform Windows

# Regression detection: compare last 2 days vs prior 2 days
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --compare 2

# Only new crashers (first seen within lookback window)
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --new-only

# Specific version, sorted by recency
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --version 1.73. --order last-seen

# Last 30 days, CSV for spreadsheet
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --format csv --days 30

# Dry run to see the query without executing
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --dry-run

# NDJSON for piping to jq
python3 ./.claude/skills/top-crashers/top-crashers.py --project "$BACKTRACE_PROJECT" --format ndjson --limit 5 | jq .fingerprint

---

Script Details

Location: ./.claude/skills/top-crashers/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:

---

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