Monitoring Overview
Understand how Nebutra monitors errors, performance, and logs using Sentry and the structured @nebutra/logger package.
Nebutra's monitoring stack gives you full visibility into application health across both the Next.js frontend and the Hono API gateway.
What Is Monitored
| Layer | Tool | What It Captures |
|---|---|---|
| Client-side errors | Sentry (browser SDK) | Unhandled exceptions, React error boundaries |
| Server-side errors | Sentry (Node SDK) | API errors, unhandled promise rejections |
| Performance | Sentry Tracing | HTTP request spans, DB query durations, p99 latency |
| Structured logs | @nebutra/logger | All info / warn / error events with tenant context |
| Release tracking | Sentry Releases | Source maps uploaded per deployment, commit context |
| Product analytics | PostHog | Funnels, retention, session replay, feature usage |
Responsibility Boundary
| Concern | Owner |
|---|---|
| Code failure, stack trace, release regression | Sentry |
| User journey, funnel drop-off, session replay | PostHog |
| Request-local structured events and trace IDs | @nebutra/logger + OpenTelemetry |
| Campaign links and invite attribution | Dub via createAnalyticsClient |
PostHog and Sentry can be correlated with shared userId, organizationId,
request ID, and release values, but they should not replace each other.
Architecture
Application code
│
▼
@nebutra/logger ──────────────────────────────────► stdout (JSON)
│ │
│ (warn / error levels) │
▼ ▼
Sentry SDK Log aggregator (optional)
│ (Datadog, Loki, CloudWatch)
▼
Sentry Cloud
│
├──► Error tracking (issues, stack traces)
├──► Performance monitoring (traces, spans)
└──► Alerts (email, Slack, PagerDuty)Every warn and error log emitted by @nebutra/logger is automatically forwarded as a Sentry breadcrumb or event. You do not need to call Sentry.captureException manually — the logger handles it.
Alert Channels
Sentry supports multiple alert destinations. Recommended configuration:
| Severity | Alert channel |
|---|---|
| New error (first occurrence) | Slack #eng-alerts |
| Error spike (>10 new errors in 1 hour) | Slack #eng-alerts + email |
| P1 (high-volume unhandled errors) | PagerDuty |
| Performance regression (p99 > 2s) | Slack #eng-alerts |
Configure alert rules in Sentry under Alerts → Create Alert Rule.
Key Metrics to Watch
Error Rate
- Target: < 0.1% of requests resulting in a 5xx error
- Alert threshold: > 5 errors/minute sustained for 5 minutes
- Dashboard: Sentry → Issues tab, filtered by environment
API Latency (p99)
- Target: p99 < 500ms for all
/api/v1/*endpoints - Alert threshold: p99 > 2s for any endpoint over a 15-minute window
- Dashboard: Sentry → Performance → Transactions
Quota Utilisation
- Source:
quota_warningandquota_exceededevents (PostHog + logger) - Target: < 5% of tenants hitting quota exceeded in any month
- Dashboard: Admin panel
/admin/analytics
Environment Variables
# Sentry — server-side (API gateway + Next.js server components)
SENTRY_DSN=https://[email protected]/XXXX
SENTRY_AUTH_TOKEN=sntrys_xxxxxxxxxxxx # for source map upload in CI
SENTRY_ORG=your-sentry-org-slug
SENTRY_PROJECT=nebutra
# Sentry — client-side (browser, must be NEXT_PUBLIC_)
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/XXXX
# PostHog — server-side product events
POSTHOG_KEY=phc_xxxxxxxxxxxx
POSTHOG_HOST=https://us.i.posthog.com
# PostHog — browser SDK
NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.comSENTRY_AUTH_TOKEN grants write access to your Sentry org. Never expose it in client-side code or commit it to version control. Store it as a CI secret (GitHub Actions secret / Vercel environment variable with server-only scope).
Disabling Monitoring in Development
By default, Sentry is disabled in development environments to avoid polluting production data. This is controlled by the NODE_ENV check in @nebutra/logger:
# .env.local — Sentry is a no-op when this is unset or environment is development
SENTRY_DSN= # leave empty to disable@nebutra/logger still writes structured JSON to stdout in development. You can tail it with pnpm dev 2>&1 | jq '.' for a formatted view.
Sentry Setup
Configure Sentry error tracking, performance monitoring, and release tracking.
Structured Logs
Learn how to use @nebutra/logger for structured, tenant-aware logging.
Analytics Overview
Product analytics with PostHog and marketing analytics with Dub.co.
Deployment
CI/CD pipeline configuration including source map uploads and release tracking.
How is this guide?
Last updated on