Skip to main content

​
PostHog Product Analytics — Event Catalogue

SDKs:
  • posthog-js in ui/packages/website
  • posthog-js in ui/packages/app
  • posthog-node in zombiectl
  • posthog-zig in zombied
PostHog is one of two observability tools (with Grafana). Langfuse is no longer part of the stack.

​
Provisioning Contract

One PostHog project key is stored per environment:
VaultItemField
ZMB_CD_DEVposthog-devcredential
ZMB_CD_PRODposthog-prodcredential
These values are propagated through the standard playbook/check flow:
  • bootstrap: playbooks/001_bootstrap/001_playbook.md
  • preflight: playbooks/002_preflight/001_playbook.md
  • credential gate: playbooks/002_preflight/001_gate.sh
  • M2 gate section: playbooks/gates/m2_001/section-2-procurement-readiness.sh

​
Surface Configuration

SurfaceEnv varSDKDefault host
WebsiteVITE_POSTHOG_KEYposthog-jshttps://us.i.posthog.com
AppNEXT_PUBLIC_POSTHOG_KEYposthog-jshttps://us.i.posthog.com
zombied API + workerPOSTHOG_API_KEYposthog-zighttps://us.i.posthog.com
zombiectl CLIZOMBIE_POSTHOG_KEYposthog-nodehttps://us.i.posthog.com
Optional host overrides remain available in code, but vault provisioning only requires the key.

​
Website Events

Emitter: ui/packages/website/src/analytics/posthog.ts
EventTypical propertiesDescription
signup_startedsource, surface, mode, pathWebsite signup funnel entered
signup_completedsource, surface, mode, pathWebsite signup flow completed
navigation_clickedsource, surface, target, pathPrimary website navigation interaction
lead_capture_clickedsource, surface, cta_id, pathLead form CTA clicked
lead_capture_openedsource, surface, component, pathLead form/modal opened
lead_capture_submittedsource, surface, status, utm_*, pathLead form submitted
lead_capture_failedsource, surface, status, pathLead form submit failed

​
App Events

Emitters:
  • ui/packages/app/instrumentation-client.ts
  • ui/packages/app/components/analytics/AnalyticsBootstrap.tsx
  • dashboard pages and cards in ui/packages/app/app/(dashboard) and ui/packages/app/components/domain
Allowed app properties are allowlisted in ui/packages/app/lib/analytics/posthog.ts.
zombie_id is not in the app allowlist (ALLOWED_PROP_KEYS in posthog.ts). Any attempt to track a per-zombie event from the app will silently drop the zombie_id property. For per-zombie analytics, use server-side events (zombie_triggered / zombie_completed) or query the activity stream (core.activity_events) via the API.
EventTypical propertiesDescription
page_navigation_startedsource, surface, pathNext.js router transition started
ui_runtime_errorsource, surface, path, error_messageBrowser runtime error or unhandled rejection
navigation_clickedsource, surface, target, pathDashboard shell navigation clicked
workspace_list_viewedsource, surface, workspace_count, pathWorkspace index viewed
workspace_card_clickedsource, surface, workspace_id, workspace_plan, paused, pathWorkspace selected from card
workspace_detail_viewedsource, surface, workspace_id, active_run_id, active_run_status, pathWorkspace detail page viewed
run_row_clickedsource, surface, workspace_id, run_id, run_status, run_attempts, pathRun selected from table/list
run_detail_viewedsource, surface, workspace_id, run_id, run_status, has_error, has_pr_url, pathRun detail page viewed
Identity:
  • user identification happens in AnalyticsBootstrap.tsx
  • distinct fields: user_id, email

​
CLI Events

Emitters:
  • lifecycle: zombiectl/src/cli.js
  • domain commands: zombiectl/src/commands/*.js
CLI properties are sanitized to strings before capture. Shared command context may include user_id, email, workspace_id, run_id, agent_id, proposal_id, score, error_code, reason.
EventTypical propertiesDescription
cli_command_startedcommand, args, context idsCommand invocation started
cli_command_finishedcommand, exit_code, context idsCommand invocation completed
cli_errorcommand, error_code, reasonTop-level CLI failure
user_authenticateduser_id, emailLogin or auth success
login_completeduser_id, emailDevice/browser login completed
logout_completeduser_idLocal logout completed
workspace_add_completedworkspace_idWorkspace create/add completed
workspace_list_viewedworkspace_id or countsWorkspace list displayed
workspace_removedworkspace_idWorkspace removed
specs_syncedworkspace_idSpecs sync completed
run_queuedworkspace_id, run_idRun trigger completed
run_status_viewedworkspace_id, run_id, run_statusRun status displayed
runs_list_viewedworkspace_idRuns list displayed
harness_compiledworkspace_id, agent_idHarness compile completed
harness_active_viewedworkspace_id, agent_idActive harness shown
harness_activatedworkspace_id, agent_idHarness profile activated
harness_source_uploadedworkspace_id, agent_idHarness source uploaded
agent_scores_viewedworkspace_id, agent_id, scoreAgent score view displayed
agent_profile_viewedworkspace_id, agent_idAgent profile displayed
agent_improvement_report_viewedworkspace_id, agent_idImprovement report displayed
agent_proposals_viewedworkspace_id, agent_idProposal list displayed
agent_proposal_approvedworkspace_id, agent_id, proposal_idProposal approved
agent_proposal_rejectedworkspace_id, agent_id, proposal_id, reasonProposal rejected
agent_proposal_vetoedworkspace_id, agent_id, proposal_id, reasonProposal vetoed
agent_harness_revertedworkspace_id, agent_id, proposal_idHarness revert executed

​
Runtime Events

Emitters live in src/observability/telemetry_events.zig (typed event structs) and src/observability/telemetry.zig (backend wrapper that forwards to PostHog).

​
Startup Lifecycle

EventEmitterPropertiesDescription
server_startedcmd/serve.zigport, worker_concurrencyHTTP server ready to accept traffic
worker_startedcmd/worker.zigconcurrencyWorker threads spawned
startup_failedcmd/worker.zigcommand, phase, reasonFatal startup failure (after PostHog init)

​
Auth Lifecycle

EventEmitterPropertiesDescription
auth_login_completedauth_sessions_http.zigsession_id, request_idCLI auth session completed (OIDC device flow)
auth_rejectedcommon.zigreason, request_idBearer token auth failed

​
Workspace Lifecycle

EventEmitterPropertiesDescription
workspace_createdworkspaces_lifecycle.zigworkspace_id, tenant_id, repo_url, request_idNew workspace provisioned via API
workspace_github_connectedgithub_callback.zigworkspace_id, installation_id, request_idGitHub App OAuth callback completed

​
Zombie Lifecycle

Server-side events emitted as each inbound webhook is accepted and each zombie delivery resolves. Both carry zombie_id, workspace_id, and event_id so they correlate with activity stream rows and Grafana traces.
EventEmitterPropertiesDescription
zombie_triggeredwebhooks.zig (via event loop)workspace_id, zombie_id, event_id, sourceInbound zombie trigger that passed signature + dedupe
zombie_completedevent_loop_helpers.zigworkspace_id, zombie_id, event_id, tokens, wall_ms, exit_status, time_to_first_token_msZombie event delivered to completion

​
Run Lifecycle

These run_* events originate from the pipeline execution path. Zombie-era deliveries emit zombie_triggered and zombie_completed instead (see Zombie Lifecycle above). The pipeline path is retained for operators who are still running legacy-era runs alongside zombie-era deliveries.
EventEmitterPropertiesDescription
run_startedruns/start.zigrun_id, workspace_id, spec_id, mode, request_idRun enqueued
run_retriedruns/retry.zigrun_id, workspace_id, attempt, request_idRun retry enqueued
run_completedpipeline/worker_stage_executor.zigrun_id, workspace_id, verdict, duration_msRun finished
run_failedpipeline/worker_stage_executor.zigrun_id, workspace_id, reason, duration_msRun failed

​
Agent & Scoring

EventEmitterPropertiesDescription
agent_completedpipeline/worker_stage_executor.zigrun_id, workspace_id, actor, tokens, duration_ms, exit_statusAgent stage execution finished
agent.run.scoredpipeline/scoring.zigrun_id, workspace_id, agent_id, score, tier, score_formula_version, axis_scores, weight_snapshot, scored_at, axis_completion, axis_error_rate, axis_latency, axis_resourceQuality score computed
agent.scoring.failedpipeline/scoring.zigrun_id, workspace_id, errorScoring computation failed
agent.trust.earnedpipeline/scoring.zigrun_id, workspace_id, agent_id, consecutive_count_at_eventConsecutive positive score streak
agent.trust.lostpipeline/scoring.zigrun_id, workspace_id, agent_id, consecutive_count_at_eventTrust state dropped
agent.harness.changedpipeline/scoring.zigagent_id, proposal_id, workspace_id, approval_mode, trigger_reason, fields_changedHarness config mutation applied
agent.improvement.stalledpipeline/scoring.zigrun_id, workspace_id, agent_id, proposal_id, consecutive_negative_deltasScore declining after proposal

​
Policy & Billing

EventEmitterPropertiesDescription
entitlement_rejectedhandler-levelworkspace_id, boundary, reason_code, request_idPlan limit hit
profile_activatedhandler-levelworkspace_id, agent_id, config_version_id, run_snapshot_version, request_idAgent harness profile activated
billing_lifecycle_eventhandler-levelworkspace_id, event_type, reason, plan_tier, billing_status, request_idPlan transitions and payment events
api_errorhandler-levelerror_code, message, request_id, workspace_idUZ-* error code fired at HTTP boundary

​
Error Code Coverage

Code PrefixPostHog Coverage
UZ-AUTH-*auth_rejected captures auth failures
UZ-ENTL-*entitlement_rejected and api_error
UZ-BILLING-*billing_lifecycle_event and api_error
UZ-STARTUP-*startup_failed
UZ-WORKSPACE-*api_error for billing/workspace enforcement failures
Browser/runtime UI failuresui_runtime_error in Next.js app
CLI command failurescli_error in zombiectl
UZ-SANDBOX-*structured logs and metrics first; correlate with PostHog run lifecycle via trace_id and run_id

​
Adding New Events

  1. Add or extend the surface helper closest to the emitter (posthog.ts, CLI analytics helper, or telemetry_events.zig).
  2. Keep analytics fail-open and non-blocking.
  3. Allowlist or sanitize properties before capture.
  4. Add unit or integration coverage for the new event path.
  5. Update this document and the relevant done-spec if the surface contract changed.