use-sentry

Sentry

The complete Sentry observability lifecycle: autonomous stack research & zero-to-one setup, deep 4-pillar feature auditing, and agent-driven production incident triage.

Decision tree (The 3 Modes)

What is your objective?
├── Mode 1: Sentry is NOT in the project OR user says "set up / initialize Sentry"
│   ├── Step 1: Detect runtime, framework & architecture (MCP, crawler, API, CLI)
│   ├── Step 2: Research stack patterns via research-mcp (max 20 keywords): `references/research/research-mcp-protocol.md`
│   ├── Step 3: Choose keyword matrix: `references/research/stack-keyword-matrices.md`
│   ├── Step 4: Step-by-step setup guide: `references/modes/mode-1-init.md`
│   └── Step 5: Stack blueprint: `references/architectures/` (mcp, playwright, fastify, nextjs, cli, python, go)
│
├── Mode 2: Sentry IS already installed OR user asks "audit / improve our Sentry"
│   ├── Step 1: Run feature audit scanner: `bash scripts/audit-project.sh`
│   ├── Step 2: Full 4-pillar audit & gap analysis guide: `references/modes/mode-2-audit.md`
│   ├── Pillar 1 (Error Tracking): `references/error-tracking/` (capture, sourcemaps, fingerprints, inbound-filters, merges)
│   ├── Pillar 2 (Breadcrumbs & Context): `references/breadcrumbs-context/` (system, ui, tags, feedback, device)
│   ├── Pillar 3 (Logging & Analytics): `references/logging-analytics/` (structured-logs, pin-to-top, log-explorer, discover)
│   └── Pillar 4 (Performance & Replay): `references/performance-replay/` (spans, asynclocalstorage, replay, crons)
│
└── Mode 3: "Something is broken in prod" / Triage alerts / Debug incident
    ├── Step 1: Run triage scanner: `bash scripts/triage-issues.sh`
    ├── Step 2: 4-rung triage guide: `references/modes/mode-3-debug.md`
    ├── Step 3: Fast diagnosis in 1 call: `references/cli-tooling/modern-sentry-cli.md`
    ├── Step 4: Trace-to-log correlation: `references/logging-analytics/log-explorer-queries.md`
    └── Step 5: Safe mutations & post-fix verification: `references/verification/post-fix-verification.md`

Quick start

Mode 1: Setup in New Project

# 1. Check credentials safely (~/.sentryclirc)
bash scripts/detect-creds.sh

# 2. Test envelope tunnel connectivity & ISP sinkhole defense
bash scripts/verify-tunnel.sh <PROJECT_ID_OR_DSN>

Mode 2: Audit Existing Project

# Run automated feature adoption scanner across 4 pillars
bash scripts/audit-project.sh .

Mode 3: Triage Production Errors

# List top unresolved errors ranked by frequency
bash scripts/triage-issues.sh <org>/<project>

# Diagnose specific issue in 1 single token-efficient call
sentry issue view <ID> --json > /tmp/iss.json
jq -r '.event.entries[] | select(.type=="exception") | .data.values[].stacktrace.frames[]? | select(.inApp) | "\(.filename):\(.lineNo) in \(.function)"' /tmp/iss.json

The 4-Rung Debugging Funnel

Rung 0  Triage        issue list   -> what is broken, ranked by frequency (cheap)
Rung 1  Diagnose      issue view   -> ONE issue + embedded latest event   (usually solves it)
Rung 2  Corroborate   explore/logs -> multi-event tag patterns, trace logs (only if Rung 1 is thin)
Rung 3  Deep Discover queries/repro-> agent discovers root cause locally   (independent reasoning)

Key patterns

1. Mandatory Envelope Tunneling (Defeating ISP DNS Sinkholes)

In Turkey (TTNet 195.175.254.2) and captive networks, *.ingest.*sentry.io is intercepted, throwing DEPTH_ZERO_SELF_SIGNED_CERT. Deriving tunnel: https://sentry.io/api/${projectId}/envelope/ routes through trusted Cloudflare edge IPs and guarantees 100% delivery.

2. Defense-in-Depth Redaction

Hook sanitizers into beforeSend and beforeBreadcrumb. Scrub authorization, x-api-key, session cookies, and strip bearer JWTs in WebSocket or browser URLs (cdpWsUrl?jwt=...).

3. Zero-Network Offline Test Gate

If SENTRY_DSN is empty or missing, initSentry() must cleanly no-op. Offline test suites (npm test) must run 100% network-free and spend $0.

4. Standalone CLI Guaranteed Flush

CLI scripts terminate immediately on exit. Always wrap the execution pipeline in try/catch and execute await flushSentry(3000) before process.exit().

Common pitfalls

Minimal reading sets

"I need to initialize Sentry in a new repository"

• references/modes/mode-1-init.md
• references/research/research-mcp-protocol.md
• references/network-tunneling/envelope-tunneling.md
• references/privacy-redaction/credential-redaction-rules.md

"I need to audit our Sentry setup and implement missing features"

• references/modes/mode-2-audit.md
• references/error-tracking/sourcemaps-pipeline.md
• references/breadcrumbs-context/system-breadcrumbs.md
• references/logging-analytics/structured-logs.md
• references/performance-replay/distributed-tracing-spans.md

"I need to debug an MCP server or cloud browser application"

• references/architectures/mcp-server-sentry.md
• references/architectures/cloud-browsers-playwright.md
• references/privacy-redaction/url-jwt-sanitization.md

"Production is throwing 500s right now"

• references/modes/mode-3-debug.md
• references/cli-tooling/modern-sentry-cli.md
• references/logging-analytics/log-explorer-queries.md
• references/verification/post-fix-verification.md

Reference files

Guardrails

• Never commit real auth tokens (sntryu_, sntrys_) to git; store them in ~/.sentryclirc or .env.
• In MCP servers using stdio, NEVER write Sentry logs or debug output to stdout; always use stderr.
• Never log raw WebSocket URLs containing JWT tokens (cdpWsUrl?jwt=...).
• Never disable TLS verification (NODE_TLS_REJECT_UNAUTHORIZED=0); use envelope tunneling instead.
• Never let an offline test suite make network requests to Sentry; no-op when SENTRY_DSN is empty.
• Always call await flushSentry(3000) before calling process.exit() in CLI scripts.
• Never resolve, archive, or merge an issue without explicit user authorization or empirical proof.