Sentry Observability

Production error tracking with two modes: Setup (add Sentry) and Operations (use Sentry).

Quick Detection

Check if Sentry is configured in current project

~/.claude/skills/sentry-observability/scripts/detect_sentry.sh

Setup Mode

For projects without Sentry. Proactively suggest when:

• New Next.js project detected (no @sentry/* in package.json)

• User mentions deploying to production

• Discussing error handling patterns

Initialize Sentry in current project

~/.claude/skills/sentry-observability/scripts/init_sentry.sh

Verify setup after installation

~/.claude/skills/sentry-observability/scripts/verify_setup.sh

Operations Mode

For projects with Sentry. Use for triage and monitoring.

List unresolved issues (powers /triage)

~/.claude/skills/sentry-observability/scripts/list_issues.sh --env production

Get priority-scored issues (triage algorithm)

~/.claude/skills/sentry-observability/scripts/triage_score.sh --json

Get full context for an issue

~/.claude/skills/sentry-observability/scripts/issue_detail.sh PROJ-123

Create alert rule

~/.claude/skills/sentry-observability/scripts/create_alert.sh --name "New Errors" --type issue

Mark issue resolved

~/.claude/skills/sentry-observability/scripts/resolve_issue.sh PROJ-123

Core Principles

• Vercel Integration First - Use marketplace, not manual tokens

• Clean Environments - "production" not "vercel-production"

• Security by Default - PII redaction, hide source maps

• CLI Automation - Version-controlled alerts

• Cost Awareness - Free tier = 5k errors/month

• Env-Controlled Sampling - Never hardcode tracesSampleRate: 1

tracesSampleRate Configuration

NEVER hardcode tracesSampleRate: 1 (100%) - exhausts quota in production.

// sentry.*.config.ts function getTracesSampleRate(): number { const rate = parseFloat(process.env.NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE || ""); if (isNaN(rate)) return 0.1; // Default 10% return Math.max(0, Math.min(1, rate)); // Clamp 0-1 }

Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, tracesSampleRate: getTracesSampleRate(), // ... });

Add to .env.example :

Traces sample rate (0-1, default 0.1 = 10% of requests traced)

NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0.1

Environment Variables

Required (in ~/.secrets or project .env.local)

SENTRY_AUTH_TOKEN / SENTRY_MASTER_TOKEN # API access SENTRY_ORG # Organization slug SENTRY_DSN # Project DSN

Auto-detected per project

SENTRY_PROJECT # From .sentryclirc or .env.local

Decision Trees

Should I Set Up Sentry?

Is this a production application? ├─ YES → Is Sentry already configured? │ ├─ NO → Run init_sentry.sh │ └─ YES → Run verify_setup.sh to check health └─ NO → Skip (development/prototype only)

Triage Priority (from /triage)

Score = Events(1x) + Users(5x) + Severity(3x) + Recency(2x) + Env(4x) Higher score = Higher priority

References

• Setup Guide - Full setup walkthrough

• Configuration - Advanced config patterns

• PII Redaction - Security patterns

• Session Replay - Visual debugging

• Troubleshooting - Common issues

• Anti-Patterns - What NOT to do

Philosophy

Observability Is Not Optional: Production errors without monitoring = invisible failures.

Proactive Setup: Suggest Sentry when starting new projects. Don't wait for the first production incident.

Security First: PII redaction is non-negotiable. Privacy violations >> lost debugging info.

Cost Awareness: Free tier (5k errors/month) is enough for most projects.