Sentry Error Tracking skill for Codex

Done well means: the issue list reflects real distinct bugs, each issue has a readable stack trace tied to a release and an owner, the top issues by user impact are being worked on, and noise is filtered at the source rather than ignored by habit.

Inspect first

1. Read AGENTS.md; find the SDK init (rg -n "Sentry.init|sentry_sdk.init|SentryAndroid|SentrySdk.Init") and note dsn, release, environment, sample rates, before_send, integrations.
2. Check how releases are created and whether source maps or debug symbols are uploaded in CI (rg -n "sentry-cli|@sentry/.*-plugin|sentry-cli sourcemaps").
3. If the user can give access, read the project’s issue stream. Querying the Sentry API or its MCP server needs network and an auth token the user provides; never ask for the token in chat history if an environment variable or keychain works.
4. For first-time SDK installation or framework wiring, use $sentry-integration; this skill assumes events already arrive.

Triage order

Work the stream in this order each week (or each day for a busy product):

Priority	Query (issue search)	Action
1. Regressions	is:unresolved is:regressed (or the Regressed tab)	Reopened after a fix: assign to whoever shipped the release
2. New in latest release	is:unresolved firstRelease:<version>	Likely caused by this deploy; decide rollback or hotfix
3. Highest user impact	sort by Users, is:unresolved	Fix the top few, not the top fifty
4. Escalating	the Escalating / For Review views	Check whether volume trend is real
5. Long tail	is:unresolved lastSeen:+30d	Resolve stale ones; archive known third-party noise

For each issue decide one of: fix now (assign, link ticket), fix later (ticket with priority), resolve in next release (fix merged), archive until condition (noise with a threshold, for example “until it affects 100 more users”), or merge (duplicate). Never mass-archive to make a number go down; that hides regressions.

Readable stack traces

• JavaScript: generate source maps in the production build, inject debug IDs and upload with the same release. Use the bundler plugin (@sentry/vite-plugin, @sentry/webpack-plugin) or the CLI:

sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload --release "$RELEASE" ./dist

Do not serve .map files publicly unless you intend to; upload then delete them from the deploy artifact.

• Native, iOS, Android: upload dSYMs, ProGuard/R8 mappings and debug files with sentry-cli debug-files upload in CI.
• Python, Go, Java, Ruby: traces resolve server-side; make sure in-app frames are correct so grouping uses your code, not the framework.

Verify one recent event shows original file names and line numbers. If it shows app.3f9c1.js:1:28473, the release name or debug ID does not match the upload.

Releases and environments

export RELEASE="checkout-web@$(git rev-parse --short HEAD)"
sentry-cli releases new "$RELEASE"
sentry-cli releases set-commits "$RELEASE" --auto
sentry-cli releases finalize "$RELEASE"
sentry-cli deploys new --release "$RELEASE" -e production

The same release string must be passed to Sentry.init. Associating commits enables suspect commits and “resolved in next release”. All CLI calls need network and SENTRY_AUTH_TOKEN; creating deploy records is visible to the team, so run them in CI rather than ad hoc from a laptop.

Fixing grouping

Symptoms and fixes:

Symptom	Cause	Fix
Same bug split across many issues	Dynamic values in message, different minified frames per release, varying call paths	Fingerprint rule on error type, or stack trace rules marking wrappers as not in-app
Many bugs merged in one issue	Generic wrapper (HttpError, fetch failed) catches everything	Fingerprint including endpoint or upstream status; throw specific error types
Grouped by vendor code	Third-party frames considered in-app	Stack trace rule -app for vendor paths

Project settings, Issue Grouping, fingerprint rules (server-side, no deploy needed):

error.type:ConnectionRefusedError -> upstream-connection-refused
error.type:TimeoutError message:"*payments*" -> payments-timeout

Stack trace rules:

stack.abs_path:**/node_modules/** -app
stack.function:handleError -group

Client-side when the grouping key is only known in code:

import sentry_sdk

with sentry_sdk.new_scope() as scope:
    scope.fingerprint = ["upstream-error", upstream_name, str(status_code)]
    sentry_sdk.capture_exception(err)

Sentry.withScope((scope) => {
  scope.setFingerprint(['upstream-error', upstreamName, String(status)]);
  Sentry.captureException(err);
});

Grouping changes apply to new events; existing issues are not regrouped. Merge the old duplicates by hand after the rule is live.

Noise control at the source

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.RELEASE,
  environment: process.env.APP_ENV,
  sendDefaultPii: false,
  ignoreErrors: ['ResizeObserver loop completed with undelivered notifications'],
  denyUrls: [/extensions\//i, /^chrome:\/\//i],
  beforeSend(event, hint) {
    const err = hint.originalException;
    if (err && err.name === 'AbortError') return null; // user navigated away
    return event;
  },
});

• Drop expected conditions (client aborts, 404s you raised on purpose) in beforeSend or by not reporting them, instead of archiving them weekly.
• Enable inbound filters for browser extensions, legacy browsers and known crawlers.
• Rate-limit noisy keys with spike protection and per-key rate limits rather than lowering the global sample rate, which drops rare real errors too.
• Scrub PII: keep sendDefaultPii: false (Python send_default_pii=False), add server-side data scrubbing rules for tokens and emails, and check one event’s raw JSON.

Workflow

• Confirm release, environment and source maps on a fresh event
• Triage regressions, then new-in-release, then top by users
• Fix grouping for the worst split and merged issues
• Move recurring noise into filters or beforeSend
• Assign owners (ownership rules or code owners) so new issues route themselves
• Mark fixed issues “resolved in next release” so regressions are detected

Verification

• A test error thrown in staging (Sentry.captureException(new Error('sentry-smoke'))) appears with the right release, environment, readable frames and owner.
• After a grouping rule, trigger two variants and confirm they land in one issue (or two, if splitting).
• Weekly: count of unresolved issues with >1 user should trend down, not just total count.

Output

A triage report: top issues by users with decision and owner, regressions linked to releases, grouping changes made, filters added, and anything archived with its condition.

Gotchas

• Sample rate for errors (sampleRate) is not the same as tracesSampleRate; lowering the wrong one loses errors.
• Release names must match exactly between SDK, source map upload and deploy record, including the package prefix.
• Errors swallowed and logged but never thrown or captured do not reach Sentry; check catch blocks that only console.error.
• Resolving an issue without a release lets the same bug reopen silently as “new”.