Observability And Errors

Observability & Errors

Overview

You can't fix what you can't see. A production SaaS needs three signals: error tracking (Sentry) for exceptions with stack + context, structured logs (JSON with a correlation id) for tracing a request, and product analytics (PostHog) for what users actually do. Add a global error boundary, attach tenant/user/request context to every signal, and scrub secrets and PII before anything leaves the process.

When to use

• Standing up a new app's logging/monitoring.
• Debugging issues you can't reproduce locally.
• You need to know which features are used or where users drop off.

Structured logging with context

// src/server/log.ts
import "server-only";

export function logger(ctx: { requestId: string; orgId?: string; userId?: string }) {
  const base = { ...ctx, ts: new Date().toISOString() };
  return {
    info: (msg: string, data?: object) => console.log(JSON.stringify({ level: "info", msg, ...base, ...data })),
    error: (msg: string, err?: unknown) =>
      console.error(JSON.stringify({ level: "error", msg, ...base, err: serializeError(err) })),
  };
}

Generate a requestId per request and thread it (and orgId) through logs and into Sentry's scope — now one search reconstructs a whole request across services.

Error tracking

import * as Sentry from "@sentry/nextjs";

Sentry.withScope((scope) => {
  scope.setTag("orgId", org.id);
  scope.setUser({ id: user.id });          // id only, not email/PII
  Sentry.captureException(err);
});

Use Next.js error.tsx / global-error.tsx boundaries to show a friendly fallback and report the error.

Analytics (sparingly)

• Track meaningful events (project_created, subscription_upgraded), not every click.
• Identify by stable user id; set org as a group. Keep a typed event list so names don't drift.

Pitfalls

• Logging secrets/PII — tokens, passwords, full request bodies, card data. Scrub before logging; send ids, not emails.
• console.log soup — unstructured strings are ungreppable. Emit JSON with a correlation id.
• Swallowing errors — catch {} hides outages. Capture with context, then handle.
• No source maps in prod — Sentry stack traces are useless without them; upload on build.
• Tracking everything — noisy analytics cost money and bury the signal. Track decisions, not clicks.

Hand-off

Errors, logs, and events you can actually act on. deployment-and-ci wires source maps + env keys; background-jobs and payments-stripe report failures here.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: param087
• Source: param087/saas-starter-skills
• License: MIT

Install and usage instructions live in the source repository linked above.