Sentry

Configure Sentry for error tracking, performance monitoring, and release tracking in Nebutra.

Sentry provides Nebutra with real-time error tracking, distributed performance tracing, and release-correlated debugging. Both the Next.js frontend and the Hono API gateway are instrumented out of the box.

Prerequisites

A Sentry account — sentry.io (Cloud) or self-hosted

A Nebutra project ready for deployment

Access to your CI/CD environment secrets (GitHub Actions or Vercel)

Setup

In your Sentry organisation, create a new project. Choose Next.js as the platform for the landing page and web app. Create a second project for the Node.js API gateway if you want separate error streams.

From Project Settings → Client Keys (DSN), copy the DSN. It looks like:

https://[email protected]/123456

Add the following to your deployment environment. In Vercel, use Environment Variables with the correct scope (Preview / Production):

# Server-side (Next.js server + API gateway)
SENTRY_DSN=https://[email protected]/XXXX
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=nebutra
SENTRY_AUTH_TOKEN=sntrys_xxxxxxxxxxxx

# Client-side (browser SDK — must be prefixed)
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/XXXX

The auth token is used to upload source maps during the build. Add it as a GitHub Actions secret named SENTRY_AUTH_TOKEN or as a Vercel environment variable scoped to build only.

Deploy to a staging environment and trigger a test error:

// Temporary — remove after verifying
throw new Error("Sentry connectivity test");

Check Sentry → Issues for the event within 30 seconds.

Source Maps

Source maps are uploaded automatically by the @sentry/nextjs Webpack plugin during next build. This requires SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT to be set at build time.

When source maps are configured correctly, Sentry stack traces show your original TypeScript source instead of minified JS.

Source maps are deleted from the deployed bundle after upload. End users cannot download them.

Performance Monitoring

Performance monitoring is auto-instrumented for:

Next.js: All page navigations, server components, and API route handlers

Hono: All HTTP routes via the @sentry/node HTTP integration

Database queries: Prisma spans via the Sentry Prisma integration

Trace sampling is controlled by the tracesSampleRate option. The Nebutra default is 0.1 in production (10% of requests):

// sentry.server.config.ts (auto-generated by @sentry/nextjs)
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
  environment: process.env.NODE_ENV,
});

Increase tracesSampleRate temporarily when debugging a performance regression, then lower it again to manage event volume and cost.

Tenant Context Enrichment

Nebutra automatically attaches org and user context to every Sentry event so you can filter issues by tenant:

import * as Sentry from "@sentry/nextjs";
import { getCurrentTenant } from "@nebutra/tenant";

// Called in middleware after tenant resolution
export function setSentryTenantContext() {
  const tenant = getCurrentTenant();
  if (!tenant) return;

  Sentry.setUser({ id: tenant.userId });
  Sentry.setTag("tenantId", tenant.tenantId);
  Sentry.setTag("plan", tenant.plan);
}

This is already wired into Nebutra's middleware chain. You do not need to call it manually in application code.

Alert Rules

Configure these alert rules in Sentry → Alerts → Create Alert Rule:

New Error Type (First Occurrence)

Condition: A new issue is created

Action: Notify Slack #eng-alerts

Error Spike

Condition: Number of events in an issue exceeds 10 in 1 hour

Action: Notify Slack #eng-alerts + send email to on-call

Unhandled Promise Rejection Spike

Condition: mechanism.type:unhandledrejection events > 5/minute

Action: PagerDuty incident

Performance Regression

Condition: p75 transaction duration exceeds 2000ms

Action: Notify Slack #eng-perf

Release Tracking

Sentry correlates errors with the exact code version that caused them. Releases are created automatically during CI via the Sentry Webpack plugin when SENTRY_AUTH_TOKEN is set.

To manually create a release (e.g. from a custom deploy script):

npx @sentry/cli releases new "$RELEASE_VERSION"
npx @sentry/cli releases set-commits "$RELEASE_VERSION" --auto
npx @sentry/cli releases finalize "$RELEASE_VERSION"
npx @sentry/cli releases deploys "$RELEASE_VERSION" new -e production

Set RELEASE_VERSION to your git SHA or semantic version tag. Sentry uses this to show which commit introduced a regression.

GitHub Integration

Connect Sentry to your GitHub repository in Sentry Settings → Integrations → GitHub. This enables:

Automatic suspect commit identification for new issues

"Resolve in commit" workflow from Sentry issues

Deploy tracking correlated with GitHub releases