debug-sentry-monitor

Sentry Monitor

Degree of freedom: MIXED. Triage bucket and root cause [HIGH freedom]; resolve-only-after-verify [LOW freedom — run exactly].

Triage, fix, and audit Sentry on any project via the sentry MCP. Auto-detects config.

How to reason

1. Observe — issue type, frames, users, first-seen, release
2. Interpret — app frame vs extension noise; new vs regression
3. Classify — Noise / Code Bug / Data Bug / Performance / Regression / Config Gap
4. Severity — regressions and multi-user crashes first; never resolve Performance

Worked example

Observe: 80 events of TypeError: undefined.email on /account, started at release 1.14.0. Interpret: app frames in the profile card; correlates with the onboarding PR. Classify: Data Bug + Regression — API null for incomplete profiles. Fix: handle null at the contract; do not resolve until the fix is committed and the loop is green.

Self-critique before reporting

• No resolve without proof — issue stays unresolved if the fix is unverified
• No band-aid — ?. / swallowed catch is not the sole fix
• Bucket is one — Noise is not used to mute an app-frame crash
• Right owner — one named bug through PR → workflow-fix-and-ship

Critical Rules

NEVER resolve an issue without a verified fix. Resolving means "this will not happen again." If you cannot prove that, leave it unresolved.

NEVER apply a band-aid fix. Wrapping code in try/catch, adding ?. chains, or guarding with Array.isArray() are symptom suppressors. Only use defensive coding after fixing the root cause, to harden against truly unpredictable external input.

Understand the WHY before touching any code.

Research before fixing non-trivial bugs. Use firecrawl_search + firecrawl_scrape to find best practices for the specific error pattern before implementing a fix.

Step 0: Auto-Detect Project Configuration

Before making any Sentry MCP calls, discover the project's Sentry setup.

0a. Find Organization and Project

First, try to detect from local config files. Search for these (in order):

1. .sentryclirc — contains [defaults] with org and project
2. sentry.properties — contains defaults.org and defaults.project
3. .env, .env.local, .env.production — look for SENTRY_ORG, SENTRY_PROJECT, SENTRY_DSN, SENTRY_AUTH_TOKEN
4. sentry.client.config.ts, sentry.client.config.js — Next.js Sentry config
5. sentry.server.config.ts, sentry.server.config.js — Next.js server Sentry config
6. next.config.js / next.config.mjs — withSentryConfig() wrapper
7. package.json — check for @sentry/* packages to detect SDK

If local detection fails, use the MCP to discover:

sentry:find_organizations

Then for the target org:

sentry:find_projects
{
 "organizationSlug": "<ORG_SLUG>",
 "regionUrl": "<REGION_URL>"
}

0b. Detect Framework and Platform

Read package.json (or equivalent) to determine:

0c. Locate Sentry Config Files

Search for the Sentry initialization and noise filtering:

Grep for: Sentry.init, sentryInit, initSentry
Grep for: ignoreErrors, beforeSend, denyUrls
Grep for: ErrorBoundary, error-boundary, errorBoundary
Grep for: logger, logging, winston, pino
Grep for: web-vitals, webVitals, reportWebVitals

0d. Record Detected Configuration

ORG_SLUG: [detected or ask user]
PROJECT_SLUG: [detected or ask user]
REGION_URL: [detected or ask user — typically https://us.sentry.io or https://de.sentry.io]
FRAMEWORK: [detected from packages]
PLATFORM: [browser | server | hybrid]
SENTRY_CONFIG: [path to Sentry.init file]
NOISE_FILTER: [path to file with ignoreErrors/beforeSend]
ERROR_BOUNDARY: [path to error boundary component, if any]
LOGGER: [path to logging utility, if any]

If any critical values cannot be detected, ask the user.

Step 1: Fetch Issues

Run these two MCP calls in parallel:

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "query": "all unresolved issues from the last 7 days",
 "limit": 50
}

sentry:search_events
{
 "organizationSlug": "<ORG_SLUG>",
 "projectSlug": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "query": "count of errors grouped by error type in the last 7 days",
 "limit": 50
}

Also check for regressions (issues that were resolved but re-opened):

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "query": "regressed issues in the last 14 days",
 "limit": 20
}

If no issues are found, report "No unresolved issues in the last 7 days" and proceed to the Architecture Audit (Step 8).

Step 2: Get Issue Details

For each issue with >1 event or >0 users impacted:

sentry:get_sentry_resource
{
 "organizationSlug": "<ORG_SLUG>",
 "resourceType": "issue",
 "resourceId": "<ISSUE_ID>"
}

Batch up to 4 calls in parallel per round.

For hard-to-diagnose issues, also fetch breadcrumbs:

sentry:get_sentry_resource
{
 "organizationSlug": "<ORG_SLUG>",
 "resourceType": "breadcrumbs",
 "resourceId": "<ISSUE_ID>"
}

And optionally use Seer for AI-assisted root cause analysis:

sentry:analyze_issue_with_seer
{
 "organizationSlug": "<ORG_SLUG>",
 "regionUrl": "<REGION_URL>",
 "issueId": "<ISSUE_ID>"
}

For understanding issue distribution, check tag values:

sentry:get_issue_tag_values
{
 "organizationSlug": "<ORG_SLUG>",
 "regionUrl": "<REGION_URL>",
 "issueId": "<ISSUE_ID>",
 "tagKey": "browser"
}

Common tag keys: url, browser, browser.name, os, environment, release, device, user.

Step 3: Triage

Classify each issue into exactly one bucket:

Priority order: Regressions first, then Code Bugs and Data Bugs, then Noise, then Config Gaps. Performance is always deferred.

3a. Seer AI Analysis for High-Impact Issues

For any issue classified as Code Bug, Data Bug, or Regression that meets either threshold:

• >10 events (high frequency)
• >5 affected users (high impact)

Run Sentry's AI root-cause analysis before manual investigation:

sentry:analyze_issue_with_seer
{
 "organizationSlug": "<ORG_SLUG>",
 "issueId": "<ISSUE_ID>"
}

Seer provides:

• Root cause explanation with code-level detail
• Specific file locations and line numbers where the error originates
• Concrete code fix suggestions you can apply directly

How to use Seer results:

• If Seer identifies a clear root cause with a specific fix → start from that fix in Step 4, validate it against the codebase, and apply if correct.
• If Seer's analysis is inconclusive or too generic → proceed with manual root cause analysis in Step 4 as normal.
• Always include Seer's analysis in the triage report (Step 8) regardless of whether you used the fix.

Note: Seer results are cached — subsequent calls for the same issue return instantly. Analysis for new issues takes ~2-5 minutes.

Step 4: Root Cause Analysis (for Code Bugs and Data Bugs)

Do NOT skip or shortcut this step.

4a. Read the Full Error Context

From the Sentry issue details, extract:

• Exception type and message — the exact error
• Full stacktrace — every frame, not just the top
• Breadcrumbs — what happened leading up to the error
• Tags — browser, OS, URL, user, environment, release
• Additional data / context — request payload, state snapshots
• Event frequency pattern — when did it start? Does it correlate with a deploy?

4b. Check Release Correlation

sentry:find_releases
{
 "organizationSlug": "<ORG_SLUG>",
 "regionUrl": "<REGION_URL>",
 "projectSlug": "<PROJECT_SLUG>"
}

If the issue started after a specific release, check what changed in that release:

git log --oneline <previous-release-tag>..<current-release-tag>

4c. Trace the Code Path

1. Start from the crash site: Read the full function where the error was thrown.
2. Walk up the call chain: For each app-code frame in the stacktrace, read the file and function.
3. Walk down to the data source: If the error involves unexpected data, trace where that data comes from:

• Database query? Read the query, check the schema.
• React state/props? Find where the state is set.
• URL param or user input? Check validation/parsing.
• Cache or store? Check invalidation and staleness.

4. Check recent changes: git log --oneline -20 -- <file> on culprit files.

4d. Research Best Practices Before Fixing

For non-trivial bugs, research the correct fix pattern:

firecrawl:firecrawl_search
{
 "query": "<framework> <error-type> best practice fix <current year>",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Then scrape the most authoritative result:

firecrawl:firecrawl_scrape
{
 "url": "<best-result-url>",
 "formats": ["markdown"],
 "onlyMainContent": true
}

4e. Formulate the Root Cause

Before writing any fix, state:

1. What happened: The specific runtime state that caused the error
2. Why it happened: The upstream reason that state was possible
3. Where to fix it: The correct layer — usually NOT the crash site, but where bad state originates

4f. Validate Against Anti-Patterns

4g. Check for Side Effects

Before applying the fix:

• Are there other callers of the function you're changing?
• Will the fix change return type or behavior for other consumers?
• Does the fix require updating types, tests, or related components?

Step 5: Apply Fixes

Noise Fixes

Read the project's Sentry config file (detected in Step 0c). Locate the ignoreErrors array or beforeSend function.

Universal noise patterns (safe to add to any web project):

// Browser/extension noise
/^Script error/,
"ResizeObserver loop",
"Non-Error promise rejection captured",
/vid_mate_check/,
/_avast_submit/,

// Network noise (external)
"Failed to fetch",
"Load failed",
"net::ERR_",
"AbortError",
"The operation was aborted",
"cancelled",

// Chunk loading (deployment race)
"ChunkLoadError",
"Loading chunk",
"Failed to fetch dynamically imported module",

Framework-specific noise (add only if the framework is detected):

React/Next.js:

"Hydration failed",
"server rendered HTML didn't match",
"Minified React error #418",
"Minified React error #423",
"Minified React error #425",

HMR/Dev-only:

"Fast Refresh",
"performing full reload",
"Parsing ecmascript source code failed",

Service Worker:

"ServiceWorker",
"Failed to register a ServiceWorker",

Noise validation: Before classifying something as noise, verify:

• The error message does NOT originate from app code
• There are NO app frames in the stacktrace
• The error cannot be triggered by a real user action

Code Bug / Data Bug Fixes

1. Fix at the root cause layer identified in Step 4e.
2. Make invalid state unrepresentable where possible.
3. Follow project conventions (read README files, existing patterns).
4. If the fix requires schema changes or infra work, flag for manual follow-up.

Performance Fixes

Do NOT attempt. Do NOT resolve. Leave unresolved. Note in the summary.

Config Gap Fixes

Implement in the relevant config file based on detected framework.

Step 6: Verify Before Resolving

You may only resolve an issue if ALL of the following are true:

• Root cause identified (not just the symptom)
• Fix addresses root cause (not just suppresses the error)
• Fix does not introduce new issues for other callers
• For Noise: error genuinely originates outside app code
• For Code/Data Bugs: full code path read, fix is logically correct
• You have NOT merely added ?., try/catch, or type guards as the sole fix

If any checkbox fails, leave the issue unresolved and add it to "Requires Manual Follow-Up."

Step 7: Resolve in Sentry

For each verified fix:

sentry:update_issue
{
 "organizationSlug": "<ORG_SLUG>",
 "regionUrl": "<REGION_URL>",
 "issueId": "<ISSUE_ID>",
 "status": "resolved"
}

Batch up to 4 calls in parallel. Do NOT resolve performance issues.

Step 8: Architecture Audit (Proactive Enhancement)

After triaging existing issues (or if no issues exist), audit the Sentry setup itself to identify monitoring gaps and architectural shortcomings.

8a. SDK Configuration Audit

Read the Sentry config file(s) detected in Step 0c. Check each setting:

Framework-specific integration checks:

Further reading

• 8b. Monitoring Coverage Audit and more

Complement: Sentry catches code-thrown errors. Mushi Mushi catches user-felt friction that never triggers an exception — dead buttons, 12-second screens, broken layouts on one device. Install alongside Sentry: npx mushi-mushi.