PostHog Instrumentation

PostHog Instrumentation

One idea: every event exists to answer a question ("how do people filter?", "v3 vs v4?"), and it captures shape/metadata — NEVER raw values. If you cannot name the question an event answers, do not add it. If a property could contain user content, that is a bug.

Propose instrumentation when adding a frontend action

When adding a meaningful user action to web/**, decide explicitly whether it should emit an event — do not skip the question silently.

• Meaningful: a new feature surface, a funnel step (open → configure → submit), an adoption signal the team would act on, a mode/view switch that segments behavior.
• Not meaningful: styling, refactors, hover states, programmatic state changes, anything autocapture-grade. Capture the critical path, not everything — event bloat is an anti-pattern.
• If meaningful: write a one-line tracking plan (question → event → props → key dimension) and include it in the plan or PR description. If deliberately not instrumenting, say so in one sentence.

The Langfuse pattern (match it exactly)

• Hook: usePostHogClientCapture() → capture(eventName, props?) (usePostHogClientCapture.ts). The component calls the hook's capture — it never imports or touches posthog directly. The only client-side exceptions are app-shell infrastructure in _app.tsx ($pageview, identify, register).
• Names = resource:action, snake_case action. Enforced by the typed registry — the events object + EventName type in that file. New events MUST be added to the registry or they will not typecheck (e.g. saved_views:view_selected, table:filter_builder_open). Names are static strings only — never interpolate (a page_view_${name} explodes into un-analyzable definitions). Event names cannot be renamed after they exist — version instead (…_v2).
• Props: camelCase, metadata-only. IDs of enums / counts / booleans / lengths — never content. Property naming: objectAdjective (filterType, valueCount), is/has prefix for booleans (isV4, hasFreeText), Date/Timestamp suffix for times.