Debug sentry monitor

Sentry Monitor

Automated Sentry issue triage, root cause analysis, fix, architecture audit, and monitoring enhancement workflow. Works with any project — auto-detects configuration from the codebase. Uses the sentry MCP server for all Sentry API operations.

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:

Package	Framework
@sentry/nextjs	Next.js
@sentry/react	React SPA
@sentry/vue	Vue.js
@sentry/svelte	SvelteKit
@sentry/node	Node.js backend
@sentry/browser	Vanilla JS
sentry-sdk (pip)	Python
sentry_sdk (pip)	Python
sentry-ruby	Ruby
@sentry/angular	Angular

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:

Bucket	Signals	Action
Noise	Extension frames, chunk load errors, browser built-in errors, dev-only environment tag, no app frames in stacktrace	Add noise filter, resolve in Sentry
Code Bug	TypeError, ReferenceError, unhandled rejection with app frames, missing function/property	Full root cause analysis (Step 4), fix, verify, resolve
Data Bug	Unexpected null/undefined from API, malformed response, stale cache, race condition	Trace data flow end-to-end (Step 4), fix at source
Performance	Slow DB query, N+1 API calls, large HTTP payload, high LCP/INP	Do NOT resolve — flag for manual follow-up
Regression	Previously resolved issue that re-opened	Highest priority — the original fix was incomplete
Config Gap	Missing Sentry feature (logging, metrics, feedback, replay), bad sampling	Implement in config files, resolve

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

Anti-Pattern	Why It's Wrong	Do Instead
Adding ?. to suppress TypeError	Hides the null; downstream gets undefined	Fix why the value is null
try/catch that swallows	Error still happens, user sees broken state	Fix the error; if unrecoverable, show user-facing message + re-report
Array.isArray() guard	Checking consumer instead of fixing producer	Fix the producer
?? [] or ?? {} fallback	Masks data loading issues	Handle loading/error states explicitly
Filtering in beforeSend	Muting a real bug	Only filter genuinely external noise
Resolving without deploying	Error recurs next session	Only resolve after fix is committed

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:

Setting	What to Check	Recommendation
dsn	Is it set from env var, not hardcoded?	Use process.env.SENTRY_DSN or equivalent
environment	Is it dynamic?	Must read from env var, not hardcoded
release	Is it set?	Required for deploy correlation and regression detection
tracesSampleRate	Is it > 0? Is it < 1.0 in production?	0.1-0.3 for production, 1.0 for dev
replaysSessionSampleRate	Is it configured?	0.1 for production
replaysOnErrorSampleRate	Is it configured?	1.0 (capture all error replays)
integrations	Are framework-appropriate integrations present?	See framework-specific recommendations below
beforeSend	Is it filtering too aggressively?	Should only filter genuinely external noise
ignoreErrors	Are patterns appropriate?	Cross-check against universal noise list

Framework-specific integration checks:

Framework	Expected Integrations
Next.js	Auto-configured by @sentry/nextjs — check withSentryConfig in next.config
React SPA	BrowserTracing, Replay
Node.js	Http, Express/Fastify/Koa, Postgres/Prisma
Python	DjangoIntegration / FlaskIntegration, SqlalchemyIntegration
Vue	BrowserTracing, Replay, Sentry.vueRouterInstrumentation

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.