configure-sentry

created	"2025-12-16T00:00:00.000Z"
modified	"2026-07-05T00:00:00.000Z"
reviewed	"2026-07-05T00:00:00.000Z"
description	Sentry error tracking setup. Use when installing the Sentry SDK, fixing hardcoded DSNs, or adding source map upload for frontend, Next.js, Node, or Python.
allowed-tools	Glob, Grep, Read, Write, Edit, Bash, AskUserQuestion, TodoWrite, WebSearch, WebFetch
args	[--check-only] [--fix] [--type <frontend|nextjs|python|node>]
argument-hint	[--check-only] [--fix] [--type <frontend|nextjs|python|node>]
name	configure-sentry

/configure:sentry

Check and configure Sentry error tracking integration against project standards.

When to Use This Skill

Use this skill when...	Use another approach when...
Setting up Sentry error tracking for a new project	Debugging a specific Sentry issue or alert (use Sentry MCP server)
Sentry-specific setup and compliance in depth	Wiring up the whole observability stack — OTel traces/metrics + logging (use /configure:instrumentation, which delegates Sentry gaps back here)
Checking Sentry SDK installation and configuration compliance	Querying Sentry events or performance data (use Sentry API/MCP)
Fixing hardcoded DSNs or missing environment variable references	Managing Sentry project settings in the Sentry dashboard
Adding source map upload and release tracking to CI/CD	Configuring Sentry alerting rules or notification channels
Verifying Sentry configuration across frontend, Next.js, Node.js, or Python projects	Installing a different error tracking tool (e.g., Bugsnag, Rollbar)
Adding profiling, structured logging, or enrichment helpers	Configuring Sentry alerting rules or notification channels
Project-level setup and compliance auditing	Day-to-day SDK usage patterns — spans, breadcrumbs, cron monitoring, replay (use typescript-plugin:typescript-sentry)

Context

• Package.json: !find . -maxdepth 1 -name \'package.json\'
• Pyproject.toml: !find . -maxdepth 1 -name \'pyproject.toml\'
• Requirements.txt: !find . -maxdepth 1 -name \'requirements.txt\'
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml' -type f
• Sentry in package.json: !find . -maxdepth 1 -name 'package.json' -exec grep -o '"@sentry/[^"]*"' {} +
• Sentry in pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml' -exec grep 'sentry' {} +
• Sentry init files: !find . -maxdepth 3 -name "*sentry*" -type f
• Next.js config: !find . -maxdepth 1 -name 'next.config.*'
• Instrumentation files: !find . -path '*/src/*' -maxdepth 2 -name 'instrumentation*' -type f
• Env files referencing DSN: !find . \( -name '.env*' -o -path '*/.github/workflows/*' \) -type f -exec grep -l 'SENTRY_DSN' {} +
• CI workflows: !find . -path '*/.github/workflows/*' -maxdepth 3 -name '*.yml'

Skills referenced: sentry (MCP server for Sentry API)

Parameters

Parse these from $ARGUMENTS:

Flag	Description
--check-only	Report status without offering fixes
--fix	Apply all fixes automatically without prompting
--type <type>	Override project type detection (frontend, nextjs, python, node)

Version Checking

CRITICAL: Before configuring Sentry SDKs, verify latest versions:

1. @sentry/vue / @sentry/react: Check npm
2. @sentry/nextjs: Check npm
3. @sentry/node: Check npm
4. sentry-sdk (Python): Check PyPI
5. @sentry/vite-plugin: Check npm

Use WebSearch or WebFetch to verify current SDK versions before configuring Sentry.

Execution

Execute this Sentry compliance check:

Step 1: Detect project type

Determine the project type to select the appropriate SDK and configuration:

1. Read .project-standards.yaml for project_type field
2. If not found, auto-detect:
   • nextjs: Has package.json with next dependency (check for @sentry/nextjs)
   • frontend: Has package.json with vue/react dependencies (without Next.js)
   • node: Has package.json with Node.js backend (express, fastify, etc.)
   • python: Has pyproject.toml or requirements.txt
3. If --type flag is provided, use that value instead

Step 2: Check SDK installation

Check for Sentry SDK based on detected project type:

Next.js:

• @sentry/nextjs in package.json dependencies
• @sentry/profiling-node (recommended for server profiling)

Frontend (Vue/React):

• @sentry/vue or @sentry/react in package.json dependencies
• @sentry/vite-plugin for source maps

Node.js Backend:

• @sentry/node in package.json dependencies
• @sentry/profiling-node (recommended)

Python:

• sentry-sdk in pyproject.toml or requirements.txt
• Framework integrations (django, flask, fastapi)

Step 3: Analyze configuration

Read the Sentry initialization files and check against the compliance tables in REFERENCE.md. Validate:

1. DSN comes from environment variables (not hardcoded)
2. Tracing sample rate is configured (different for prod vs dev)
3. Source maps are enabled (frontend/Next.js)
4. Init location is correct (Node.js: before other imports)
5. Framework integration is enabled (Python)

Additional checks for Next.js projects:

6. src/instrumentation.ts exists with register() and onRequestError exports
7. src/instrumentation-client.ts exists with client-side Sentry init
8. sentry.server.config.ts and sentry.edge.config.ts exist at project root
9. next.config.mjs wraps config with withSentryConfig()
10. Tunnel route configured (tunnelRoute: "/monitoring")
11. Source maps hidden and deleted after upload (hideSourceMaps, deleteSourcemapsAfterUpload)
12. @sentry/profiling-node listed in serverExternalPackages
13. Error boundaries exist (src/app/error.tsx, src/app/global-error.tsx)
14. Structured logging enabled (enableLogs: true)
15. Sensitive header stripping in beforeSend
16. Transaction filtering in beforeSendTransaction (drop health checks, static assets)

Step 4: Run security checks

1. Verify no hardcoded DSN in any source files
2. Check that DSN is not committed in git-tracked files
3. Verify no auth tokens in frontend code
4. Check production sample rates are reasonable (not 1.0)

Step 5: Report results

Print a compliance report with:

• Project type (detected or overridden)
• SDK version and installation status
• Configuration check results (PASS/WARN/FAIL)
• Security check results
• Missing configuration items
• Recommendations

If --check-only, stop here.

Step 6: Apply fixes (if --fix or user confirms)

1. Missing SDK: Add appropriate Sentry SDK to dependencies
2. Missing Vite plugin: Add @sentry/vite-plugin for source maps
3. Missing config file: Create Sentry initialization file using templates from REFERENCE.md
4. Hardcoded DSN: Replace with environment variable reference
5. Missing sample rates: Add recommended sample rates

Step 7: Check CI/CD integration

Verify Sentry integration in CI/CD:

• SENTRY_AUTH_TOKEN secret configured
• Source map upload step in build workflow
• Release creation on deploy

If missing, offer to add the recommended workflow steps from REFERENCE.md.

Step 8: Update standards tracking

Update or create .project-standards.yaml:

standards_version: "2025.1"
project_type: "<detected>"
last_configured: "<timestamp>"
components:
  sentry: "2025.1"

Environment Variables

Variable	Description	Required
SENTRY_DSN	Sentry Data Source Name (server-side)	Yes
NEXT_PUBLIC_SENTRY_DSN	Sentry DSN for client-side (Next.js)	Next.js only
SENTRY_ENVIRONMENT	Environment name (server-side)	Recommended
NEXT_PUBLIC_SENTRY_ENVIRONMENT	Environment name (client-side, Next.js)	Next.js only
SENTRY_ORG	Sentry organization slug	For source maps
SENTRY_PROJECT	Sentry project slug	For source maps
SENTRY_AUTH_TOKEN	Auth token for CI/CD	For source maps
NEXT_PUBLIC_SENTRY_SKIP_BUILD	Skip Sentry webpack plugin in builds	Container builds

Never commit DSN or auth tokens. Use environment variables or secrets management.

For detailed configuration check tables, initialization templates, and CI/CD workflow examples, see REFERENCE.md.

Agentic Optimizations

Context	Command
Quick compliance check	/configure:sentry --check-only
Auto-fix all issues	/configure:sentry --fix
Frontend project only	/configure:sentry --type frontend
Next.js project	/configure:sentry --type nextjs
Python project only	/configure:sentry --type python
Node.js project only	/configure:sentry --type node
Check for hardcoded DSNs	rg -l 'https://[a-f0-9]*@.*sentry\.io' --type-not env

Error Handling

• No Sentry SDK: Offer to install appropriate SDK for project type
• Hardcoded DSN: Report as FAIL, offer to fix with env var reference
• Invalid DSN format: Report error, provide DSN format guidance
• Missing Sentry project: Report warning, provide setup instructions

See Also

• /configure:instrumentation - Whole observability stack (OTel traces/metrics, structured logging); delegates Sentry gaps to this skill
• /configure:all - Run all compliance checks
• /configure:status - Quick compliance overview
• /configure:workflows - GitHub Actions integration
• typescript-plugin:typescript-sentry - Day-to-day Sentry SDK usage for Bun/Node.js/Next.js (spans, breadcrumbs, cron monitoring, replay)
• sentry MCP server - Sentry API access for project verification