Health endpoints

Read this reference when the selected observability plan needs liveness, readiness, or external uptime monitoring.

Contents

• Choose the signal
• Next.js pattern
• FastAPI pattern
• Verification

Choose the signal

• Liveness answers whether the process can serve. Keep it cheap and independent of downstream services.
• Readiness answers whether this instance can perform essential work. Probe only critical dependencies, use short timeouts, and return a non-2xx response when unavailable.
• Business checks belong in synthetic monitoring, not a public health response.

Do not expose environment names, versions, connection details, exception text, row counts, or dependency topology publicly. In serverless runtimes, process uptime is instance-local and usually not a useful service metric.

Next.js pattern

// app/api/health/live/route.ts
export async function GET() {
  return Response.json(
    { status: 'ok', timestamp: new Date().toISOString() },
    { headers: { 'Cache-Control': 'no-store' } },
  );
}

For readiness, inject a project-specific dependency check rather than assuming a users table or creating a new service-role client on every request:

// app/api/health/ready/route.ts
import { checkDatabase } from '@/lib/health/check-database';

export async function GET() {
  const result = await checkDatabase({ timeoutMs: 1_500 });
  return Response.json(
    { status: result.ok ? 'ok' : 'unavailable' },
    {
      status: result.ok ? 200 : 503,
      headers: { 'Cache-Control': 'no-store' },
    },
  );
}

Reuse the application’s server-only database client. The check should be bounded, non-mutating, and inexpensive. Protect readiness with network policy or a monitoring token if exposing dependency status creates risk.

FastAPI pattern

from datetime import datetime, timezone
from fastapi import Response

@app.get('/health/live')
async def live():
    return {
        'status': 'ok',
        'timestamp': datetime.now(timezone.utc).isoformat(),
    }

@app.get('/health/ready')
async def ready(response: Response):
    ok = await check_database(timeout_seconds=1.5)
    response.status_code = 200 if ok else 503
    return {'status': 'ok' if ok else 'unavailable'}

Verification

• Liveness returns quickly while a downstream dependency is unavailable.
• Readiness returns 200 normally and 503 under a forced dependency failure or timeout.
• Responses contain no sensitive internals and are not cached.
• The external monitor uses the expected path, interval, regions, and alert contacts.
• Record dashboard/monitor configuration as manual until actually observed.

PostHog implementation

Read this reference before changing PostHog browser/server setup, identity, page views, feature flags, or events. Check the installed posthog-js/posthog-node versions and current PostHog documentation before copying API options.

Contents

• Plan events and privacy
• Initialize
• Identity
• Typed capture
• Server capture
• Verification

Plan events and privacy

Define stable event names and required properties before installation. Avoid credentials, payment data, message/content bodies, raw prompts, unrestricted URLs/query strings, and unnecessary personal data. Email addresses are personal data; capture them only when justified by the product’s privacy/consent policy. Configure opt-out/consent, retention, replay masking, and region before production.

Initialize

Use the framework pattern recommended for the installed version. In current Next.js versions, prefer PostHog’s current App Router guidance and do not add manual page-view capture until checking whether the selected defaults already capture navigation.

'use client';

import posthog from 'posthog-js';
import { PostHogProvider as Provider } from 'posthog-js/react';

if (typeof window !== 'undefined' && process.env.NEXT_PUBLIC_POSTHOG_KEY) {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    person_profiles: 'identified_only',
    // Set capture_pageview explicitly only when the installed-version plan requires it.
  });
}

export function PostHogProvider({ children }: { children: React.ReactNode }) {
  return <Provider client={posthog}>{children}</Provider>;
}

The browser project token is designed for ingestion; do not confuse it with a personal API key. Keep personal keys and management API credentials server-only.

Identity

Use the stable internal application user ID as distinct_id. Identify only after authoritative authentication, reset on logout, and test account switching and impersonation.

posthog.identify(user.id, {
  // Include personal properties only when approved by the measurement/privacy plan.
  plan: user.plan,
});

posthog.reset();

Do not identify from untrusted query/body fields. Define how anonymous pre-login activity merges and how deletion/opt-out requests are handled.

Typed capture

type ProductEvent =
  | { event: 'project_created'; properties: { projectId: string } }
  | { event: 'generation_completed'; properties: { generationId: string; latencyMs: number } };

export function captureProductEvent(value: ProductEvent) {
  posthog.capture(value.event, value.properties);
}

Capture authoritative outcomes on the server when a browser event could be blocked, forged, or duplicated.

Server capture

Create one reusable server client per runtime pattern, pass the stable user ID, and ensure queued events are flushed according to the host lifecycle. Do not force flushAt: 1 without measuring latency/cost. Serverless and edge runtimes may require explicit shutdown/flush handling from current SDK documentation.

Verification

• Confirm exactly one expected page-view event per navigation strategy.
• Confirm typed custom events and property shapes.
• Test anonymous-to-authenticated merge, logout reset, and account switching.
• Confirm development/test traffic is separated or disabled.
• Inspect a real event for accidental personal/sensitive properties.
• For server capture, confirm delivery before the runtime exits and verify duplicate-request behavior.

Sentry implementation

Read this reference before changing Sentry initialization, source maps, boundaries, structured errors, replay, or tracing. Use the installed SDK’s current wizard/manual setup and review every generated file.

Contents

• Install and configure
• Privacy and sampling
• Boundaries and logging
• Source maps
• Verification

Install and configure

For Next.js, the current Sentry wizard may generate instrumentation files, client initialization, global-error, and withSentryConfig. Run it only when dependency installation and generated changes are in scope, then inspect the diff and adapt it to the detected Next.js/Sentry versions.

Keep DSNs where the SDK expects them. Keep source-map auth tokens and organization/project management credentials server-side and out of the application bundle.

Privacy and sampling

Choose trace/replay sampling from traffic, incident needs, and budget rather than hard-coding 10%. Before enabling replay or request data capture:

• mask text and block sensitive media/DOM regions;
• scrub authorization, cookies, tokens, payment fields, prompts, and message bodies;
• set user identity only when allowed by policy;
• honor consent and regional requirements;
• tag environment and release consistently.

Error-triggered replay can still collect personal data; it is not automatically safe because normal session replay sampling is zero.

Boundaries and logging

Use framework error files/boundaries for user recovery and capture unexpected exceptions once. Avoid duplicate capture in nested boundaries. Preserve a safe user-facing message and a retry/reset path.

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

export function captureAppError(
  error: unknown,
  context: { action?: string; requestId?: string; metadata?: Record<string, unknown> } = {},
) {
  const normalized = error instanceof Error ? error : new Error(String(error));
  Sentry.withScope((scope) => {
    if (context.action) scope.setTag('action', context.action);
    if (context.requestId) scope.setTag('request_id', context.requestId);
    if (context.metadata) scope.setExtras(context.metadata);
    Sentry.captureException(normalized);
  });
}

Metadata must be allow-listed and scrubbed. Do not attach entire request bodies or user objects.

Source maps

Upload source maps during the production build using the provider’s supported integration. Do not expose source-map tokens at runtime. Verify with a real event/release, because a successful build alone does not prove frames resolve.

Verification

• Trigger controlled client and server errors and record their event IDs.
• Confirm each error is captured once with correct environment/release tags.
• Inspect payloads/replay for redaction and masking.
• Confirm the boundary recovery/reset path works.
• Verify source frames resolve to authored code, then remove the test path.
• Exercise tracing only at the configured sampling behavior and confirm cost-sensitive data is not attached.