factory-observability

Factory observability

Each section leads with Principle (one sentence, stack-agnostic), then Why (constraint → option → tradeoff), then Recipe (the PostHog / Sentry / pino / structlog shape we use), and Failure mode when there's one to name.

Day-one stack — observability before features

Principle. PostHog + Sentry + trace IDs + structured logs go in on day one, before the first feature ships.

Why. Observability is the build's most asymmetric cost-vs-value: cheap on day one (an SDK install and a config block), expensive to backfill (every event needs a redeploy, session-replay data starts empty, six months of usage history is lost). The trap is treating it as "we'll add when we need it" — by the time you need it, the data you'd want doesn't exist.

Recipe.

Layer	Tool	Purpose
Product analytics	PostHog	Per-feature usage, funnels, session replay
Error tracking	Sentry	Exceptions, performance, source maps
Audit log	DB table (admin_actions or audit_log)	Mutation provenance, regulatory compliance
Request tracing	Trace ID middleware + logs	Cross-service debugging
Structured logs	pino (Node) / structlog (Python)	Searchable, machine-parseable

PostHog — client setup with ingest rewrite

Principle. PostHog ingest goes through your own domain via Next.js rewrites; ad-blockers drop direct PostHog calls.

Why. Browser-level ad-blockers (uBlock, Brave's shield) recognize i.posthog.com and drop ~30% of events in aggregate. Routing through /ingest on your own domain bypasses the blocklist — the events arrive, the analytics are accurate. The cost is one rewrite block; the savings are ~30% of every funnel calculation you'll ever do.

Recipe.

// src/components/PostHogProvider.tsx
'use client';

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

if (typeof window !== 'undefined') {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: '/ingest',                  // proxied — see rewrites below
    capture_pageview: false,              // we call manually with route context
    person_profiles: 'identified_only',
  });
}

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