Observability Setup

Observability Setup

Purpose

Detect production errors and performance regressions proactively. Every silent failure costs a user; observability turns silence into signal.

Universal — error capture, CWV reporting, structured logging, console.log replacement, and alert thresholds apply to any frontend. Only the error-tracking SDK and framework-specific integration hooks differ.

Procedure

1. Install and initialize an error-tracking SDK (validation loop)

   • Install the SDK and run the framework's bootstrap wizard — it initializes capture across every runtime (client, server, and edge each need their own init)
   • Trigger a test error in dev mode (e.g., throw new Error('observability test') in a request handler)
   • Verify the error appears in the dashboard within 30 seconds; if not, check init config and re-trigger
   • Confirm the stack trace is un-minified — if it shows a.b.c, source-map upload isn't wired (the wizard sets the auth token; CI must upload maps on build). Upload maps privately to the SDK but don't serve them publicly (see security-audit)
   • Tag each build with a release + git commit so errors attribute to a version and "suspect commits" work — set the release in both SDK init and the deploy step (see cicd-pipeline)
   • Do not proceed to step 2 until end-to-end capture is confirmed working
   • See Implementation for the exact wizard command and generated files

2. Wire error boundaries to the SDK

   • Every error-boundary component must report to the SDK (captureException) in addition to rendering fallback UI
   • Route-level boundaries catch first; the global / last-resort boundary fires only when the root itself throws
   • Coordinate boundary placement with async-ux-states

3. Capture server-side and mutation errors

   • Server request handlers: use the SDK's automatic request-error hook where the framework provides one
   • Server mutations / actions are often NOT auto-instrumented — wrap them explicitly (see Implementation)
   • Any catch that returns gracefully MUST report the error before returning — otherwise the failure is silent in production

4. Add user context (anonymized) AND scrub auto-captured PII

   • Attach anonymized user context (id only — never email/name) so errors group by impact (1 user vs 1000)
   • The SDK captures more than you set: request URLs/headers, breadcrumbs, and (with Session Replay) DOM and input values — these leak tokens, auth headers, and form data. Configure beforeSend scrubbing + the platform's data-scrubbing, and mask text/inputs in Session Replay. "I didn't call setUser with an email" is not enough. (see Implementation)

5. Capture Core Web Vitals

   • Use the framework's CWV reporting hook (or the web-vitals library directly) at a top-level layout
   • Forward LCP / INP / CLS / TTFB / FCP to your analytics (Sentry, Vercel Analytics, custom)
   • Track over time, alert on regression

6. Structured logging utility

   • Replace console.log with a logger utility
   • JSON format with level (debug / info / warn / error), timestamp, route, userId (anonymized)
   • Single source of truth — easy to swap backends (Sentry → Datadog → custom)

7. Strip console.log from production code

   • grep -rn 'console\.log' src/ → 0 in production code (debugger / test files OK)
   • Better: ESLint rule no-console: ['error', { allow: ['warn', 'error'] }]

7b. Control sampling, quota, and noise

• Errors are cheap; traces and Session Replay are not — set tracesSampleRate and replaysSessionSampleRate deliberately (sample a fraction in prod) or quota and cost blow up
• Filter known noise (ignoreErrors / denyUrls): browser-extension errors, ResizeObserver loop warnings, network aborts — left in, they bury real signal and burn quota
• Rate-limit or group spammy errors so one broken component doesn't flood the dashboard

8. Set alert thresholds
   • Alert on error-rate spikes and CWV regressions past target — configured in the observability platform, not the app. Alert on patterns, not every error.

Completion Criteria

• Sentry captures errors from dev test trigger
• Production stack traces are un-minified (source maps uploaded, not served publicly)
• Releases tagged with git commit (errors attribute to a version)
• All error.tsx files wired to Sentry.captureException
• Server Actions wrapped in withServerActionInstrumentation
• Auto-captured PII scrubbed (beforeSend + data scrubbing; Session Replay masked)
• useReportWebVitals reporting CWV
• Trace/Replay sampling rates set; known noise filtered (ignoreErrors/denyUrls)
• console.log count in src/ (production code) = 0
• Structured logger used for all in-app logging
• Alert thresholds configured

Output

• SDK config files: framework-specific (e.g., sentry.server.config.ts, instrumentation.ts, instrumentation-client.ts)
• Logger utility: src/lib/logger.ts with JSON structured output + level support
• CWV integration: useReportWebVitals (or equivalent) in root layout, forwarding to analytics/Sentry
• Alert config: documented in docs/observability-alerts.md — thresholds, channels, runbook links
• Smoke-test commit (after install): chore(observability): wire <SDK> + verify test capture

Implementation

React + Next.js (default — Sentry)

• Wizard: npx @sentry/wizard@latest -i nextjs — creates sentry.server.config.ts, sentry.edge.config.ts, instrumentation-client.ts (replaces the older sentry.client.config.ts), instrumentation.ts; wraps next.config.ts in withSentryConfig
• Error boundaries: in error.tsx and global-error.tsx, useEffect(() => Sentry.captureException(error), [error]); route-level error.tsx catches first, global-error.tsx only when the root layout itself throws
• Server error capture: onRequestError = Sentry.captureRequestError in instrumentation.ts (route handlers / middleware, automatic)
• Server Actions: NOT auto-captured — wrap each with Sentry.withServerActionInstrumentation(name, options?, callback)
• User context: Sentry.setUser({ id: anonymizedUserId }) — id only, never PII (email/name)
• Source maps: the wizard sets SENTRY_AUTH_TOKEN; withSentryConfig uploads on build; keep productionBrowserSourceMaps: false so maps aren't public (see security-audit)
• PII scrubbing: beforeSend to drop sensitive fields; enable server-side data scrubbing; replayIntegration({ maskAllText: true, blockAllMedia: true })
• Sampling/noise: tracesSampleRate, replaysSessionSampleRate / replaysOnErrorSampleRate; ignoreErrors / denyUrls for noise; tracePropagationTargets to link frontend spans to your API
• Release: release in init + SENTRY_RELEASE (git SHA) on deploy for suspect-commit attribution
• CWV: useReportWebVitals hook → forward to analytics

Other stacks

• Vue / Nuxt: @sentry/vue + @sentry/nuxt (Nuxt module auto-installs everything)
• SvelteKit: @sentry/sveltekit — wraps handle hook for server-side capture
• Angular: @sentry/angular — ErrorHandler injectable wires to all uncaught errors
• Alternatives to Sentry: Datadog RUM, New Relic Browser, Honeybadger, Bugsnag, LogRocket, Highlight — all support framework-agnostic browser SDKs
• Universal: web-vitals library reports CWV from any client; structured JSON logging is framework-agnostic; alert thresholds (error rate, p95 latency, CWV regression) configured in the observability platform, not the app

Related skills

• async-ux-states — error.tsx components must wire Sentry.captureException
• cicd-pipeline — Sentry release tagging on deploy
• rendering-performance — CWV reported here for the field-data picture

Reference

• Key insight encoded: global-error.tsx is last-resort only — route-level error.tsx catches first. Any catch that returns gracefully (Server Actions, route handlers) MUST call captureException before returning, otherwise the failure is silent in production. Wire CWV reporting from day one — performance regressions are invisible without it. Three setup gaps that quietly defeat observability: minified traces (upload source maps — privately, not public), the SDK auto-capturing PII (scrub via beforeSend + mask Session Replay), and unbounded trace/replay sampling (cost blowup). Tag releases with the git commit so errors attribute to a version.