Error Tracking (Sentry)

VibeReady includes Sentry integration for error tracking and performance monitoring. The setup follows a two-tier approach: start with runtime error capture, then optionally add source maps for human-readable stack traces.

Free tier: 5,000 errors per month.

---

Two-Tier Setup

Tier 1: Runtime Tracking (5 minutes)

This tier captures errors from the client, server, API routes, and middleware. Stack traces will reference minified code, but you will still see error messages, frequency, and affected users.

1. Get your DSN from sentry.io: create a Next.js project, then navigate to Project Settings, then Client Keys.

   • Copy the DSN (format: https://...@sentry.io/...).

2. Add to your local environment:

# .env.local
NEXT_PUBLIC_SENTRY_DSN="https://your-dsn@sentry.io/123456"

3. Add to CI/CD: Add the DSN to your CI/CD pipeline secrets (e.g., GitHub Secrets) so it is available during builds.

4. Restart the dev server:

make dev

What Tier 1 provides:

• Errors captured from client, server, API routes, and middleware
• Error frequency and user impact data
• Stack traces reference minified code (e.g., “Error at a.b.c (main.js:1:4567)“)

---

Tier 2: Source Maps (10 additional minutes, optional)

Source maps make stack traces fully readable, showing the original file names, line numbers, and function names (e.g., “Error at src/app/api/users/route.ts:45 in getUserData()”).

1. Get your organization and project slugs from your Sentry URL: https://sentry.io/organizations/{org}/projects/{project}/.

2. Create an auth token: navigate to Settings, then Account, then Auth Tokens, then Create New Token.

   • Scopes required: project:releases and org:read.
   • Copy the token (it is shown only once).

3. Add to your local environment:

# .env.local
SENTRY_ORG="your-org-slug"
SENTRY_PROJECT="your-project-slug"
SENTRY_AUTH_TOKEN="your-auth-token"

4. Add to CI/CD: Add all three values to your CI/CD pipeline secrets so source maps are uploaded during production builds.

5. Build: Run npm run build. Source maps are uploaded to Sentry automatically during the build process.

Note: Sentry does not use GCP Secret Manager. All Sentry configuration values are build-time only and are provided through environment variables or CI/CD secrets.

---

Testing

Trigger an error in your application and verify it appears in Sentry under your project’s Issues tab.

---

Troubleshooting

Issue	Fix
Errors not appearing	Check that NEXT_PUBLIC_SENTRY_DSN is set and restart the dev server.
Source maps not uploading	Verify all three Tier 2 environment variables are set and check build output.
Auth token errors	Verify the token has project:releases and org:read scopes.

---

Related Docs

• GCP Deployment — production deployment (Sentry uses build-time variables, not Secret Manager)