Monitoring

On This Page

The Three PipelinesErrors, OTLP logs, and source maps into PostHog.Error TrackingTwo helpers you call, plus an automatic hook that needs no wiring.Structured LoggingSix severity levels emitted over OTLP to PostHog Logs.Source MapsUploaded at build time so stack traces de-minify.The Reverse ProxySame-origin /ingest rewrites for ad-blockers and CSP.Health ProbesLiveness and readiness endpoints for uptime monitors.Env Vars At A GlancePostHog client, proxy, and build-time source-map variables.

The Three Pipelines

Product events, identify, and session replay live on Analytics. This page is the ops half of the same PostHog project.

Error Tracking

Three surfaces feed PostHog error tracking: two you call, one automatic.

Client. Use captureError from @syntaxkit/analytics/client in any error boundary. The kit's global boundary at apps/web/app/global-error.tsx does this:

"use client";
import { useEffect } from "react";
import { captureError } from "@syntaxkit/analytics/client";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    captureError(error);
  }, [error]);
  // ...render fallback UI
}

PostHog links each exception to the active session replay, so a dashboard error comes with the stack and the recent user activity that led to it.

Server. Use captureServerError(error, distinctId?, context?) from @syntaxkit/analytics/server when you catch an error and still want PostHog to see it. It awaits a flush so serverless invocations do not drop the capture:

import { captureServerError } from "@syntaxkit/analytics/server";

try {
  await doSomethingRisky();
} catch (error) {
  await captureServerError(error as Error, userId, { route: "/api/risky" });
  throw error;
}

Automatic. The onRequestError hook in apps/web/instrumentation.ts runs on every unhandled server render, route handler, or server action error. You do not wrap those paths in try/catch for capture to work.

export const onRequestError = async (err, request, context) => {
  if (analyticsEnabled && process.env.NEXT_RUNTIME === "nodejs") {
    const ctx = getPostHogContext(cookieString);

    log.error(`Server request error: ${err.message}`, {
      posthogDistinctId: ctx.distinctId,
      sessionId: ctx.sessionId,
      attributes: {
        error_name: err.name,
        error_stack: err.stack?.slice(0, 500) ?? "",
        request_path: request.path,
        request_method: request.method,
        router_kind: context.routerKind,
        route_path: context.routePath,
        route_type: context.routeType,
      },
    });

    await posthog.captureException(err, ctx.distinctId);
    await loggerProvider?.forceFlush();
  }
};

Structured Logging

Use log from @syntaxkit/analytics/logger. It wraps an OpenTelemetry logger and ships OTLP records to PostHog Logs. Six severity levels, three optional fields:

import { log } from "@syntaxkit/analytics/logger";

log.info("Stripe webhook processed", {
  posthogDistinctId,
  sessionId,
  attributes: { eventId, eventType, outcome },
});

Pass posthogDistinctId and sessionId when you have them. They link a log line to the user who triggered it. attributes is freeform structured data; PostHog Logs shows those keys as filterable columns.

The LoggerProvider lives in apps/web/instrumentation.ts with a BatchLogRecordProcessor, so logs ship in batches. The Stripe webhook handler and the auto error hook are the reference call sites.

Source Maps

When POSTHOG_API_KEY and POSTHOG_PROJECT_ID are set, @posthog/nextjs-config wraps the Next config in apps/web/next.config.ts. At next build it uploads source maps, then deletes them locally so they never ship in the runtime image:

export default process.env.POSTHOG_API_KEY && process.env.POSTHOG_PROJECT_ID
  ? withPostHogConfig(composedConfig, {
      personalApiKey: process.env.POSTHOG_API_KEY,
      projectId: process.env.POSTHOG_PROJECT_ID,
      host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
      sourcemaps: { enabled: true, deleteAfterUpload: true },
    })
  : composedConfig;

The Reverse Proxy

Client init uses api_host: "/ingest" instead of the public PostHog host. When POSTHOG_PROXY_INGEST_HOST and POSTHOG_PROXY_ASSET_HOST are set, apps/web/next.config.ts rewrites those paths to your PostHog endpoints:

async rewrites() {
  if (
    process.env.POSTHOG_PROXY_INGEST_HOST &&
    process.env.POSTHOG_PROXY_ASSET_HOST
  ) {
    return [
      {
        source: "/ingest/static/:path*",
        destination: `${process.env.POSTHOG_PROXY_ASSET_HOST}/static/:path*`,
      },
      {
        source: "/ingest/:path*",
        destination: `${process.env.POSTHOG_PROXY_INGEST_HOST}/:path*`,
      },
    ];
  }
  return [];
},

Same-origin requests avoid many ad-blockers, and the kit's strict CSP does not need posthog.com in connect-src. The proxy is optional. Without the two env vars, rewrites no-op and the client uses NEXT_PUBLIC_POSTHOG_HOST directly (CSP must allow that origin).

Health Probes

Uptime monitors should hit the plain Next routes. Matching oRPC procedures (readinessCheck, livenessCheck) exist on /rpc for in-app checks; monitors that do not speak RPC use the HTTP paths below.

See API for procedure-level detail.

Env Vars At A Glance

Where To Go Next

Also useful: Analytics for product events on the same PostHog project, and Deployment for where build-time POSTHOG_API_KEY and POSTHOG_PROJECT_ID are set per host.