multica/docs/analytics.md

Product Analytics

This document is the source of truth for the analytics events Multica ships to PostHog. Events feed the acquisition → activation → expansion funnel that drives our weekly Active Workspaces (WAW) north-star metric.

See MUL-1122 for the design context.

PostHog is reserved for user/product-behaviour events. High-volume operational / execution-lifecycle telemetry — runtime lifecycle (runtime_registered / runtime_ready / runtime_failed / runtime_offline), the agent task lifecycle (agent_task_*), and autopilot run lifecycle (autopilot_run_started / autopilot_run_completed / autopilot_run_failed) — is Prometheus-only and is not shipped to PostHog. Grafana already covers it and the per-event PostHog ingestion cost (these events dominate volume and bill at the identified-event rate) is not justified. The runtime/autopilot events are flagged by analytics.IsMetricsOnly, which metrics.RecordEvent consults to skip the PostHog Capture while still incrementing the Prometheus counter; the agent_task_* lifecycle is recorded straight to Prometheus via the typed BusinessMetrics.RecordTask* methods and has no analytics.Event at all.

Configuration

All analytics shipping is toggled by environment variables (see .env.example):

Variable	Meaning	Default
POSTHOG_API_KEY	PostHog project API key. Empty = no events are shipped.	""
POSTHOG_HOST	PostHog host (US or EU cloud, or self-hosted URL).	https://us.i.posthog.com
ANALYTICS_ENVIRONMENT	Optional override for the standard environment event property. Normalized to production, staging, or dev; defaults from APP_ENV.	APP_ENV / dev
ANALYTICS_DISABLED	Set to true/1 to force the no-op client even when POSTHOG_API_KEY is set.	""

Local dev and self-hosted instances run with POSTHOG_API_KEY="", so no events leave the process unless the operator explicitly opts in.

Self-hosted instances

Self-hosters should never inherit a Multica-issued POSTHOG_API_KEY — that would route their users' behavior to our analytics project. The defaults guarantee this:

• .env.example ships POSTHOG_API_KEY= empty. The Docker self-host compose does not set a default either.
• With the key unset, NewFromEnv returns NoopClient and logs analytics: POSTHOG_API_KEY not set, using noop client at startup — a visible confirmation that nothing is shipped.
• Operators who want their own analytics can set POSTHOG_API_KEY and POSTHOG_HOST to point at their own PostHog project (Cloud or self-hosted PostHog).
• The frontend receives the key via /api/config (planned for PR 2), so self-hosts' blank server config also disables frontend event shipping automatically — no separate frontend opt-out plumbing required.

Architecture

handler → analytics.Client.Capture(Event)   ← non-blocking, returns immediately
                    │
                    ▼
           bounded queue (1024 events)
                    │
                    ▼
     background worker: batch + POST /batch/
                    │
                    ▼
                PostHog

• analytics.Capture is never allowed to block a request handler. A broken backend must not degrade the product — when the queue is full, events are dropped and counted (visible via slog + the dropped counter on shutdown).
• Batches flush either when BatchSize is reached or every FlushEvery (default 10 s), whichever comes first.
• Close() drains remaining events during graceful shutdown. Called from server/cmd/server/main.go via defer.

Identity model

• distinct_id — always the user's UUID for logged-in events. The frontend's posthog.identify(user.id) merges any prior anonymous events under the same identity, so acquisition attribution (UTM / referrer) stays intact across signup.
• workspace_id — added to every event as a property when present. v1 uses event property filtering (free tier) rather than PostHog Groups Analytics (paid) to compute workspace-level metrics.
• PII — events carry email_domain (e.g. gmail.com), not the full email. Full email is stored once in person properties via $set_once so it's available for individual debugging but not broadcast with every event.
• Person properties ($set) — use for mutable cohort signals (role, use_case, team_size, platform_preference) that a user can legitimately change during onboarding. Event.Set on the backend maps to $set; the frontend helper is setPersonProperties() in @multica/core/analytics. Use $set_once only for values that must never be overwritten (email, initial attribution, first-completion timestamp).

Taxonomy

Every event is assigned to one dashboard category:

Category	Events
core_loop	workspace_created, agent_created, issue_created, chat_message_sent, issue_executed, autopilot_created, squad_created
onboarding_support	onboarding_started, onboarding_questionnaire_submitted, onboarding_completed, onboarding_runtime_path_selected, onboarding_runtime_detected
acquisition	signup, download_intent_expressed, download_page_viewed, download_initiated, cloud_waitlist_joined, contact_sales_submitted
ops_feedback	feedback_opened, feedback_submitted
system/noise	$pageview, $set, $identify, $autocapture, $rageclick
operational (Prometheus-only — NOT in PostHog)	runtime_registered, runtime_ready, runtime_failed, runtime_offline, agent_task_queued, agent_task_dispatched, agent_task_started, agent_task_completed, agent_task_failed, agent_task_cancelled, autopilot_run_started, autopilot_run_completed, autopilot_run_failed

The v0 core dashboard must use only core_loop plus the specific onboarding_support steps used by the activation funnel. Acquisition, feedback, and system/noise events stay in separate dashboards. The operational row is not shipped to PostHog — those signals live in Grafana via multica_* business counters (see server/internal/metrics).

Standard core properties

Canonical core events should carry these properties whenever the entity exists:

Property	Type	Notes
environment	string	production / staging / dev; stamped by backend and frontend analytics clients.
event_schema_version	int	Current version: 2.
user_id	string UUID	Human user ID when known. Agent/system events may omit it.
workspace_id	string UUID	Required for workspace-scoped events.
agent_id	string UUID	Required for agent/task events.
task_id	string UUID	Required for agent_task_* events.
issue_id / chat_session_id / autopilot_run_id	string UUID	Relevant source entity for the task/entry event.
source	string	Canonical values: onboarding, manual, chat, autopilot, api. UI surface details use surface or trigger_source.
runtime_mode	string	cloud / local when a runtime/agent task is involved.
provider	string	claude, codex, cursor, etc. when a runtime/agent task is involved.
is_demo	bool	Currently always false; reserved for future demo/test workspace filtering.

Task terminal events additionally carry duration_ms; failures carry failure_reason, error_type, and will_retry. Runtime failure events carry recoverable; runtime ready events carry runtime_id, ready_duration_ms only when it is actually measured, and daemon_id for local runtimes.

Schema v2 is the first canonical core-metrics schema. It replaces early v1 drafts that mirrored failure_reason into error_type, used recoverable for task/autopilot failures, and emitted ready_duration_ms: 0 before the registration path had a measured duration.

Event contract

signup

Fires when a new user is created. Covers both verification-code and Google OAuth entry points (findOrCreateUser is the single emission site).

Property	Type	Description
email_domain	string	Lower-cased domain portion of the user's email.
signup_source	string	Opaque attribution bundle from the frontend cookie multica_signup_source (UTM + referrer). Empty when the cookie is absent.
auth_method	string	Optional. "google" for Google OAuth signups. Absent for verification-code signups.

Person properties set with $set_once:

Property	Type	Description
email	string	Full email. Never broadcast per-event.
signup_source	string	Same as above; kept on the person for later segmentation.

workspace_created

Fires after a CreateWorkspace transaction commits successfully.

Property	Type	Description
workspace_id	string (UUID)	Added globally; present here for clarity.

Note on "first workspace" segmentation — we deliberately do not stamp an is_first_workspace boolean at emit time. Computing it correctly would require an extra column or transaction-scoped logic that still races under concurrent creates. Instead, PostHog answers the same question exactly by looking at whether the user has a prior workspace_created event (use a funnel with "first time user does X" or a cohort on person_properties.$initial_event). No information is lost.

runtime_registered

Prometheus-only — not shipped to PostHog (see the note at the top of this doc). The analytics.Event is still constructed so metrics.IncForEvent can derive the Prometheus counter; the fields below are that event shape, not a PostHog contract. Only the low-cardinality fields (runtime_mode, provider) become Prometheus labels — ids like runtime_id / daemon_id are not labels.

Fires the first time a (workspace_id, daemon_id, provider) tuple is upserted. Heartbeats and repeat registrations never re-emit. First-time detection uses Postgres xmax = 0 on the upsert RETURNING clause — no extra query, no race.

Property	Type	Description
runtime_id	string (UUID)	The newly created agent_runtime row id.
daemon_id	string	Local daemon identity when available.
runtime_mode	string	Currently local; reserved for cloud runtimes.
provider	string	e.g. "codex", "claude".
runtime_version	string	Version of the agent runtime binary.
cli_version	string	Version of the multica CLI that registered it.

distinct_id is the authenticated owner's user id when the daemon was registered via a member's JWT/PAT; daemon-token registrations fall back to workspace:<workspace_id> so PostHog doesn't bucket unrelated daemons under a single "anonymous" person.

runtime_ready

Prometheus-only — not shipped to PostHog.

Fires when a runtime is first registered in an online/ready state. This is the activation-funnel step that should replace treating runtime_registered as proof of readiness. The backend emits this only on the INSERT path for a new agent_runtime row; ordinary daemon reconnects update the existing row and do not emit another runtime_ready. Dashboard funnels should still count distinct runtime_id.

Property	Type	Description
runtime_id	string (UUID)	The agent_runtime row id.
daemon_id	string	Local daemon identity when available.
ready_duration_ms	int64	Optional. Time from registration start to ready; omitted until the registration path can measure it.
runtime_mode	string	local / cloud.
provider	string	Runtime provider.

runtime_failed

Prometheus-only — not shipped to PostHog.

Fires when runtime setup/registration fails before a ready runtime can be recorded. Today this is scoped to backend registration persistence failures; future setup flows should reuse it for provider detection or daemon boot failures.

Property	Type	Description
daemon_id	string	Local daemon identity when available.
provider	string	Runtime provider attempted.
failure_reason	string	Stable coarse reason.
error_type	string	Stable error classifier.
recoverable	bool	Whether retrying setup may succeed.

runtime_offline

Prometheus-only — not shipped to PostHog.

Fires when a runtime is explicitly deregistered or the backend sweeper marks it offline after missed heartbeats. This is not an activation step; it supports local runtime retention and drop-off diagnosis.

issue_created

Fires after an issue row is created, including manual UI/API issue creation, quick-create issue creation by an agent, and autopilot create_issue runs.

Property	Type	Description
issue_id	string (UUID)	Created issue.
agent_id	string (UUID)	Agent assignee or creating agent when applicable.
task_id	string (UUID)	Present for quick-create issue creation.
autopilot_run_id	string (UUID)	Present for autopilot-created issues.
source	string	manual, api, or autopilot.

chat_message_sent

Fires after a user chat message is persisted and the corresponding agent task is queued.

Property	Type	Description
chat_session_id	string (UUID)	Chat session.
task_id	string (UUID)	Queued agent task.
agent_id	string (UUID)	Chat agent.
source	string	Always chat.

agent task lifecycle (Prometheus-only)

Not shipped to PostHog and has no analytics.Event. The agent task lifecycle is recorded directly to Prometheus by the typed BusinessMetrics.RecordTask* methods in server/internal/service/task.go. The old PostHog event names (agent_task_queued / dispatched / started / completed / failed / cancelled) and their properties (task_id, agent_id, issue_id, chat_session_id, autopilot_run_id, duration_ms, error_type, will_retry) no longer exist anywhere — those high-cardinality ids were never Prometheus labels and must not be used in dashboards or reconciliation.

The actual metrics (defined in server/internal/metrics/business.go; label sets in server/internal/metrics/labels.go):

Metric	Type	Labels
multica_agent_task_enqueued_total	counter	source, runtime_mode
multica_agent_task_dispatched_total	counter	source, runtime_mode
multica_agent_task_started_total	counter	source, runtime_mode, provider
multica_agent_task_terminal_total	counter	source, runtime_mode, terminal_status
multica_agent_task_failed_total	counter	source, runtime_mode, failure_reason
multica_agent_task_queue_wait_seconds	histogram	source, runtime_mode
multica_agent_task_run_seconds	histogram	source, runtime_mode, terminal_status
multica_agent_task_total_seconds	histogram	source, runtime_mode, terminal_status

• terminal_status is the task's final agent_task_queue.status — completed / failed / cancelled. There is no separate completed/cancelled metric: all three land on multica_agent_task_terminal_total{terminal_status=…}. Failures additionally increment multica_agent_task_failed_total carrying the coarse failure_reason (agent_task_queue.failure_reason, default agent_error).
• Task wall-clock lives in the *_seconds histograms (queue wait / run / total), replacing the old duration_ms event property.
• source / runtime_mode / provider are the normalized label values (NormalizeTaskSource / NormalizeRuntimeMode / NormalizeRuntimeProvider).

autopilot_run_started / autopilot_run_completed / autopilot_run_failed

Prometheus-only — not shipped to PostHog. The analytics.* constructors are retained only so metrics.IncForEvent can derive the Prometheus counter; analytics.IsMetricsOnly keeps them out of PostHog. Only cadence, trigger_kind, and terminal_status become Prometheus labels — the autopilot_id / autopilot_run_id / agent_id fields below are event shape, not labels.

Fires from autopilot_run lifecycle changes. source is always autopilot; the trigger origin is carried in trigger_source (manual, schedule, webhook, or api).

Property	Type	Description
autopilot_id	string (UUID)	Autopilot definition.
autopilot_run_id	string (UUID)	Run row.
agent_id	string (UUID)	Assigned agent.
trigger_source	string	manual, schedule, webhook, or api.
duration_ms	int64	Terminal events only.
failure_reason	string	Failed events only.
error_type	string	Failed events only; stable coarse classifier such as configuration, issue_terminal, dispatch_error, task_error, or autopilot_error.
will_retry	bool	Failed events only; currently false because autopilot retry cadence is owned by triggers/schedules.

issue_executed

Fires at most once per issue — when the first task on that issue reaches terminal done state. Backed by an atomic UPDATE issue SET first_executed_at = now() WHERE id = $1 AND first_executed_at IS NULL RETURNING *; retries, re-assignments, and comment-triggered follow-up tasks all hit the WHERE clause and no-op, so the ≥1 / ≥2 / ≥5 / ≥10 funnel buckets count distinct issues, not tasks.

Property	Type	Description
issue_id	string (UUID)
task_id	string (UUID)	Completing task.
agent_id	string (UUID)	Completing agent.
source	string	manual, chat, or autopilot.
runtime_mode	string	local / cloud.
provider	string	Runtime provider.
task_duration_ms	int64	Wall-clock time between task.started_at and task.completed_at. Zero when the task was created in a completed state (rare).

distinct_id prefers the issue's human creator so agent-executed events flow into the issue-author's person profile (same place signup and workspace_created land). Agent-created issues prefix with agent: to keep PostHog from merging the agent into a user record.

Note on workspace-Nth ordinals — we deliberately do not stamp nth_issue_for_workspace at emit time. Computing it correctly would require either a serialised transaction or an advisory lock per workspace; two concurrent first-completions could otherwise both read count=1 and emit n=1. PostHog answers the same question at query time via row_number() OVER (PARTITION BY properties.workspace_id ORDER BY timestamp), and funnel steps of the form "workspace has had ≥2 issue_executed events" are expressible without the property. No information is lost.

issue_executed is the canonical PostHog core-loop success signal (the agent_task_* lifecycle that previously served per-task success dashboards is now Prometheus-only). Per-task completion counts live in Grafana via BusinessMetrics.RecordTaskTerminal; use issue_executed for the PostHog-side activation funnel and filter by source as needed.

team_invite_sent

Fires from CreateInvitation after the DB row is written.

Property	Type	Description
invited_email_domain	string	Lower-cased domain; full email lives in the invitation row, not the event.
invite_method	string	Currently always "email". Future non-email invite flows (share link, SCIM) should pass their own value.

distinct_id is the inviter's user id.

team_invite_accepted

Fires from AcceptInvitation after both the invitation row is marked accepted and the member row is inserted in the same transaction.

Property	Type	Description
days_since_invite	int64	Whole days from invitation creation to acceptance. Lets us segment "accepted same day" (warm) from "dug out of email weeks later" (cold).

distinct_id is the invitee's user id — this is the event that closes the expansion funnel.

onboarding_started

Fires once when the onboarding shell mounts and the initial workspace list has resolved. Existing-workspace users carry workspace_id; brand-new users do not have a workspace yet.

Property	Type	Description
workspace_id	string (UUID)	Present only when the user already has a workspace.
source	string	Always onboarding.

onboarding_questionnaire_submitted

Fires on the first PatchOnboarding that transitions the user's questionnaire JSONB from "at least one slot empty" to "all three filled" (team_size, role, use_case). Revisions past that point don't re-emit — the funnel counts users, not edits.

Property	Type	Description
team_size	string	solo / team / other.
role	string	developer / product_lead / writer / founder / other.
use_case	string	coding / planning / writing_research / explore / other.
team_size_has_other	bool	true when the user filled the Q1 free-text escape.
role_has_other	bool	Ditto Q2.
use_case_has_other	bool	Ditto Q3.

Person properties set with $set (not once — users can go back and change answers before submitting again):

Property	Type	Description
team_size	string	Mirrors the event property for cohort queries.
role	string	Same.
use_case	string	Same.

distinct_id is the user's id. No workspace_id — the questionnaire is per-user, not per-workspace.

agent_created

Fires on every successful POST /api/workspaces/:id/agents. Not onboarding-specific — the is_first_agent_in_workspace property isolates the Step 4 signal from later agent additions.

Property	Type	Description
agent_id	string (UUID)
provider	string	Runtime provider the agent is bound to (claude, codex, etc).
runtime_mode	string	Runtime mode copied from the bound runtime.
template	string	Template slug used to seed the agent (coding / planning / writing / assistant). Empty when the caller didn't come from a template picker.
is_first_agent_in_workspace	bool	true when the workspace had zero agents before this insert.

distinct_id is the authenticated owner's user id.

onboarding_completed

Fires from CompleteOnboarding on the first call that actually flips user.onboarded_at from NULL. Retries are idempotent server-side but deliberately do NOT re-emit, so the funnel counts first-completions only. The client sends completion_path in the POST body to label which exit the user took.

Property	Type	Description
workspace_id	string (UUID)	Present for workspace-linked onboarding completions.
completion_path	string	One of full / runtime_skipped / cloud_waitlist / skip_existing / invite_accept / unknown. See below.
joined_cloud_waitlist	bool	Derived from user.cloud_waitlist_email. Orthogonal to completion_path — a user may submit the waitlist form and still pick CLI.

Person properties set with $set_once:

Property	Type	Description
onboarded_at	string (RFC3339)	Timestamp the first completion landed. Enables cohort queries like "users onboarded before X" directly from person_properties.

completion_path values:

• full — Reached Step 5 (first_issue) with a runtime connected.
• runtime_skipped — Completed without connecting a runtime (user hit Skip in Step 3).
• cloud_waitlist — Submitted the cloud waitlist form and skipped Step 3.
• skip_existing — "I've done this before" from Welcome. The user already had a workspace.
• invite_accept — Accepted at least one workspace invitation.
• unknown — Legacy fallback when the client didn't send a path. Should stay near zero after rollout.

cloud_waitlist_joined

Fires from JoinCloudWaitlist whenever a user submits the Step 3 cloud waitlist form. Not a completion signal — it's orthogonal to the main funnel and used to size hosted-runtime interest.

Property	Type	Description
has_reason	bool	Presence flag for the free-text reason field. The free text stays in the DB; we don't broadcast it.

distinct_id is the user's id.

contact_sales_submitted

Fires from CreateContactSales after the contact_sales_inquiry row is inserted. The endpoint is public and unauthenticated, so the distinct_id is the inquiry id (no user identity to attach to). The free-text goals field stays in the DB and is never broadcast.

Property	Type	Description
inquiry_id	string	Stable inquiry id; same as distinct_id. Useful for joining to operational data.
company_size	string	Closed enum from the form dropdown (1-10, 11-50, 51-200, 201-500, 501-1000, 1000+).
country_region	string	Country / region label submitted from the dropdown.
use_case	string	Closed enum (evaluate / adopt_team / self_host / integrate / partner / other).
has_goals	bool	Presence flag for the free-text goals field.

feedback_submitted

Fires from CreateFeedback after the feedback row is inserted and the hourly per-user rate-limit check has passed. Retries within the same hour that were rate-limited (429) don't emit. The free-text message is stored in the DB and never broadcast.

Property	Type	Description
message_length_bucket	string	0-100 / 100-500 / 500-2000 / 2000+ — coarse bucket of len(message) so we can tell "quick note" from "bug report with repro steps" without leaking content.
has_images	bool	true when the markdown contains at least one  image reference — signals bug reports with visual evidence.
platform	string	Client platform from X-Client-Platform header (web / desktop). Omitted when the header is absent.
app_version	string	Client version from X-Client-Version header. Omitted when absent.

distinct_id is the submitter's user id; workspace_id is attached from the modal's current-workspace context and may be empty when feedback is sent from a pre-workspace surface.

Frontend-only events

• $pageview — fired by the web tracker (apps/web/components/pageview-tracker.tsx) on Next.js App Router pathname changes, and by the desktop tracker (apps/desktop/.../pageview-tracker.tsx) on visible-surface changes. Both mount once at the root and drive the acquisition funnel's / → signup step. posthog-js's automatic pageview capture is disabled in initAnalytics so we own the event shape. capturePageview (packages/core/analytics) section-normalizes the path before emitting: query string / hash are stripped and resource-id segments are collapsed, so /acme/issues/8d5c… and /acme/issues/MUL-12 both report as /acme/issues, and consecutive views of the same section are deduplicated. This keeps PostHog at section granularity rather than billing a $pageview per resource or per filter/sort/search change. The tracker is deliberately NOT keyed on the query string.

• onboarding_runtime_path_selected — fired from packages/views/onboarding/steps/step-platform-fork.tsx when the web user clicks one of the three Step 3 fork cards (before any server call happens, so it's frontend-only). Properties: path (download_desktop / cli / cloud_waitlist), source (onboarding), surface (step3), workspace_id, and is_mac. Also writes platform_preference (web / desktop) to person properties so every subsequent event on the user can be broken down by chosen platform. Note: semantic "download intent" is now better served by download_intent_expressed below — path: "download_desktop" signals Step 3 path choice specifically, not actual download start.

• onboarding_runtime_detected — fired from packages/views/onboarding/steps/step-runtime-connect.tsx (desktop Step 3) once per mount, when the scanning phase resolves — either immediately on first runtime registration, or after the 5 s empty timeout. Answers the question "did the user have any AI CLI installed on this machine when they hit Step 3" — currently unanswerable from the existing funnel because the bundled daemon fails to register at all when zero CLIs are on PATH, so runtime_registered is silent on that cohort. Splits completion_path=runtime_skipped into "had CLIs, skipped anyway" vs "no CLIs available, had no choice". Properties:

  • source: onboarding.
  • surface: step3_desktop.
  • workspace_id: current onboarding workspace.
  • outcome: found (at least one runtime registered before the 5 s grace window expired) or empty (none registered by then).
  • runtime_count: number of runtimes visible to this user at resolution time.
  • online_count: subset of runtime_count whose status is online.
  • providers: sorted array of distinct provider names (e.g. ["claude", "codex"]).
  • has_claude / has_codex / has_cursor: convenience booleans derived from providers for funnel breakdowns without array filtering in HogQL.
  • detect_ms: wall-clock ms from component mount to resolution. Surfaces daemon boot latency — found events with a high detect_ms approach the timeout threshold and inform whether to lengthen the grace period.

  Person properties set with $set:

  • has_any_cli: boolean — cohort signal for "user has at least one local AI CLI detected on this machine".
  • detected_cli_count: number — granular cohort signal.

  Not emitted from the web Step 3 (step-platform-fork.tsx) — web users don't run the bundled daemon, so their runtime list reflects daemons from other machines and would corrupt the "CLI installed locally" signal.

• download_intent_expressed — fired whenever a user clicks a CTA that points at the /download page. Surfaces five sources across the funnel, letting the top-of-funnel entry be split cleanly. Wrapper lives in packages/core/analytics/download.ts (captureDownloadIntent). Properties:

  • source: landing_hero / landing_footer / login / welcome / step3 Also writes platform_preference: "desktop" to person properties.

• download_page_viewed — fired once per /download mount after OS detect resolves (apps/web/app/(landing)/download/download-client.tsx). Properties:

  • detected_os: mac / windows / linux / unknown
  • detected_arch: arm64 / x64 / unknown
  • detect_confident: true when detect used userAgentData.getHighEntropyValues (Chromium); false when it fell back to the UA string (Safari on Mac always lands here — lets us isolate the arm64-default-for-Intel risk cohort).
  • version_available: false when the GitHub API fetch failed and the page is in the "Version unavailable" degraded state. Also writes first_detected_os / first_detected_arch via $set_once so every downstream event gains a platform dimension without re-emitting.

• download_initiated — fired when the user clicks a specific installer link on /download. Both the hero CTA and the All Platforms matrix rows emit this; split by primary_cta. Properties:

  • platform: mac / windows / linux
  • arch: arm64 / x64
  • format: dmg / zip / exe / appimage / deb / rpm
  • version: release tag (e.g. v0.2.13) — correlates adoption with release cadence.
  • primary_cta: true for the hero-recommended installer, false for a manual pick from the All Platforms matrix.
  • matched_detect: true when the chosen platform+arch matches what the page detected. false lets us quantify detect misses from the single event (no cross-join needed).

• feedback_opened — fired when the in-app Feedback modal mounts (user clicked "Feedback" in the Help launcher). Paired with the backend's feedback_submitted to give a completion rate for the form. Wrapper lives in packages/core/analytics/feedback.ts (captureFeedbackOpened). Properties:

  • source: help_menu (reserved — future entry points like keyboard shortcut or error-toast CTA will pass their own value)
  • workspace_id: string (UUID) when the modal opens inside a workspace. Omitted on pre-workspace surfaces.

• Attribution is NOT a separate event; UTM + referrer origin are written to the multica_signup_source cookie on the first anonymous pageview and read by the backend's signup emission. The cookie carries a JSON payload URL-encoded at write time (encodeURIComponent) and URL-decoded at read time (url.QueryUnescape) — the JSON is never mid-truncated; individual values are capped at 96 chars before JSON.stringify, and the entire payload is dropped if it still exceeds 512 chars. That way PostHog sees either intact JSON or nothing at all.

Reconciliation

Per-task completion is no longer shipped to PostHog. Task success now reconciles DB ↔ Prometheus instead of DB ↔ PostHog: the BusinessMetrics.RecordTaskTerminal counter (exported as a multica_* task metric) should track the operational source of truth:

SELECT date_trunc('day', completed_at AT TIME ZONE 'UTC') AS day,
       count(*) AS db_completed_tasks
FROM agent_task_queue
WHERE status = 'completed'
  AND completed_at >= now() - interval '30 days'
GROUP BY 1
ORDER BY 1;

Compare against the equivalent Prometheus counter in Grafana. The expected difference should be near zero; sustained drift means either an emission site is missing or the metrics pipeline is unhealthy.

On the PostHog side, issue_executed remains the product-level success signal (at most one per issue) and can be reconciled against issue.first_executed_at if needed.

Governance

Before adding, renaming, or removing any event:

1. Update this document first.
2. Update server/internal/analytics/events.go constants and helpers to match.
3. PR description must state which existing funnel / insight is affected.