Eng Posthog Event Naming Convention

PostHog Event Naming Convention

What it does

This skill defines the canonical naming convention, property schema, and governance rules for all PostHog analytics events emitted by the legal AI product. Consistent event naming is the prerequisite for building reliable funnels, feature-flag cohorts, and the LLM quality trend dashboard that feeds [[eval-leaderboard-updater]].

Setup / auth

PostHog project is configured via:

• POSTHOG_KEY — public client-side key (safe to expose in frontend)
• POSTHOG_HOST — self-hosted or app.posthog.com
• POSTHOG_SERVER_KEY — server-side key for Edge Function calls (never expose to browser)

All events must include distinct_id (the user's UUID, never email/name in the event itself — PII goes through [[eng-pii-redaction-preprocessor]]).

Capabilities

Naming structure

<noun>_<verb>

• Noun is the product object: session, skill, document, chat, nda, contract, user, workspace, billing, eval.
• Verb is the past-tense action: started, completed, failed, viewed, clicked, upgraded, cancelled.
• Always lowercase, words joined with _.
• No "clicked" or "viewed" as the sole event name — always include a noun: button_clicked is useless; skill_selector_clicked is queryable.

Event taxonomy

Session & auth

Chat & skill routing

Document workflow

Billing & tier

Eval (server-side only)

Required properties on every event

{
  distinct_id: string;       // user UUID
  tenant_id: string;         // workspace/firm UUID
  session_id: string;        // current session UUID
  platform: "web" | "ios" | "android";
  app_version: string;       // semver
  environment: "production" | "staging" | "local";
}

Per-event additional properties

chat_message_sent

{
  message_length_chars: number;
  language_detected: "ar" | "en" | "fr" | "mixed";
  has_attachment: boolean;
}

skill_routed

{
  skill_id: string;          // e.g. "draft-nda-unilateral"
  skill_category: string;    // e.g. "draft"
  confidence: number;        // router confidence 0-1
  latency_ms: number;
}

chat_response_completed

{
  skill_id: string;
  tokens_input: number;
  tokens_output: number;
  latency_ms: number;
  tier: "free" | "pro" | "business" | "byo";
  rubric_score?: number;     // if real-time eval enabled
}

Usage patterns

Frontend (React)

import posthog from "posthog-js";

posthog.capture("skill_routed", {
  skill_id: routedSkill.id,
  skill_category: routedSkill.category,
  confidence: routedSkill.confidence,
  latency_ms: Date.now() - startTime,
});

Edge Function (server-side)

import { PostHog } from "posthog-node";
const ph = new PostHog(Deno.env.get("POSTHOG_SERVER_KEY")!);

ph.capture({
  distinctId: userId,
  event: "eval_run_completed",
  properties: {
    tenant_id: tenantId,
    run_id: runId,
    aggregate_score: score,
    regression_detected: hasRegression,
    environment: "production",
  },
});
await ph.shutdown();

Permissions & safety

• Never include raw user message content in event properties. Use message_length_chars instead.
• Never include full names, email addresses, or phone numbers in event properties. Use UUIDs.
• environment: "local" events should not appear in the production PostHog project. Gate on env var.
• Billing events (upgrade_completed) must be cross-validated against Stripe webhook receipts.

Failure modes

Related skills

• [[eng-pii-redaction-preprocessor]] — ensures message content is never passed raw to analytics
• [[eng-token-budget-by-tier]] — tier and budget data feeds chat_response_completed properties
• [[eval-benchmark-runner]] — consumes eval_run_* events
• [[eval-leaderboard-updater]] — reads PostHog quality-trend data