Observability — PostHog Analytics

HB Plastics uses PostHog (project 439335) for product analytics, funnel tracking, and worker health monitoring across all Cloudflare Workers and websites.

Quick Reference

PostHog project: 439335
Host: https://us.i.posthog.com
Token: Set as POSTHOG_API_KEY worker secret (write-only project key)
Events fire silently when key is absent — safe to deploy code before setting secrets

How to Send Events

From a Cloudflare Worker

import { capturePostHogEvent, captureWorkerError, measureDuration, createRequestId } from '@hbplastics/worker-lib/posthog';

// Simple event
await capturePostHogEvent(env, ctx, {
  event: 'shipping_quote_requested',
  distinctId: 'worker:shipping-calculator',
  properties: { destination_state: 'VIC', package_count: 3 },
  app: 'shipping-calculator',
  surface: 'worker',
  brand: 'hb-plastics-group',
});

// Error capture (sanitises tokens/keys automatically)
await captureWorkerError(env, ctx, request, error, { route: '/api/quotes' }, {
  app: 'shipping-calculator',
  worker: 'shipping-calculator',
});

// Timing
const elapsed = measureDuration();
// ... do work ...
const durationMs = elapsed();

From a Browser (React SPA)

import { trackEvent } from '../lib/analytics';
trackEvent('marketing_report_loaded', { report_type: 'overview', duration_ms: 320 });

From Perspex Online (Astro)

PostHog funnel events fire automatically through poTrack() in src/lib/track.ts. The poTrack function fans out to GA4, Meta Pixel, server conversions, and PostHog simultaneously. No separate PostHog calls needed — just use poTrack('purchase', { ... }).

Event Naming

All events use lower_snake_case with a domain prefix:

Prefix	Domain
`shipping_`	Shipping quotes and orders
`calculator_`	Pricing calculators
`checkout_` / `purchase_`	Ecommerce funnel
`marketing_`	Marketing dashboard
`ai_`	LLM/AI requests
`worker_`	Worker health
`cron_`	Scheduled jobs
`webhook_`	Webhook processing

Full event catalogue: docs/observability/posthog-event-catalogue.md

Required Properties

Every event must include:

Property	Description
`app`	Application name (e.g. `shipping-calculator`)
`environment`	`production`, `staging`, `development`
`surface`	`worker`, `website`, `calculator`, `dashboard`
`event_version`	Schema version (currently `1`)

Privacy Rules

Never send to PostHog:

Customer name, email, phone, address
Payment details (card numbers, CVV, bank accounts)
API keys, tokens, secrets, passwords
Full error stacks with credentials
Complete request/response payloads

The shared helper automatically redacts 25+ sensitive key patterns and sanitises error messages. Use postcodes as prefix-only (first 2 digits).

AI Observability

LLM calls through @hbplastics/worker-lib/llm.js (callLLM) automatically emit ai_request_completed and ai_request_failed events with token counts, model, provider, duration, and cache hit status. Pass ctx (the Worker execution context) to enable non-blocking capture:

const data = await callLLM(env, { workload: 'copy_gen', system, messages, ctx });

Dashboards

Six dashboards are defined in docs/observability/posthog-dashboards.md:

Shipping Operations — quote volume, success rates, carrier breakdown
Calculator & Ecommerce Funnel — calculator → cart → checkout → purchase
AI Usage & Cost — token consumption, response times, provider reliability
Worker Health — error rates, latency, cron/webhook status
Marketing Dashboard — dashboard usage and report performance
Deployments — deploy frequency and post-deploy error correlation

Alerts

Critical alerts (immediate action): shipping quote failure spike, worker error rate >5%, zero quotes during business hours, checkout failures.

Warning alerts (investigate): AI provider failures, external API failures, cron failures, webhook failures, slow shipping quotes.

Full alert specs: docs/observability/posthog-alerts.md

Event catalogue: docs/observability/posthog-event-catalogue.md
Discovery report: docs/observability/posthog-discovery.md
Release tracking: docs/observability/posthog-release-tracking.md
Dashboards: docs/observability/posthog-dashboards.md
Alerts: docs/observability/posthog-alerts.md
Privacy & governance: docs/observability/posthog-privacy-and-governance.md
Rollout checklist: docs/observability/posthog-rollout-checklist.md

Observability — PostHog analytics