feat(analytics): add PostHog product analytics

[waleedlatif1]

Summary

• Add typed PostHog event catalog (lib/posthog/events.ts) as single source of truth for all event names and property shapes
• Add lazy singleton server client (lib/posthog/server.ts) with fire-and-forget captureServerEvent — no latency impact, graceful no-op when PostHog is disabled
• Add client helper (lib/posthog/client.ts) for Zustand stores using dynamic import pattern
• Wire 48 events across the full user journey: signup, subscription lifecycle, workspace management, workflow execution, blocks, knowledge bases, tables, credentials, MCP servers, custom tools, BYOK keys, notification channels, copilot, A2A agents, API keys, and settings navigation
• Group analytics on every workspace-scoped event (groups: { workspace }) for workspace-level PostHog queries
• $set_once activation milestones (e.g. first_execution_at, first_workflow_created_at) for cohort analysis
• $set person properties on billing events to track plan state
• Track api_key_created source (settings vs deploy_modal) to understand where users discover API keys
• All captures are fire-and-forget — no new env vars, no new providers, zero impact on self-hosted deployments

Type of Change

• New feature

Testing

Tested manually — verified events appear in PostHog Live Events for workflow execution, block add/remove, settings navigation, knowledge base open, and message sent.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Apr 3, 2026 7:46am

[cursor]

PR Summary

Medium Risk
Touches many API routes and key workflow/auth execution paths to emit PostHog events; while designed as fire-and-forget, mistakes in event capture (e.g., missing IDs/groups) could introduce subtle runtime noise or minor overhead.

Overview
Introduces a typed PostHog analytics layer via a shared event catalog (lib/posthog/events.ts) plus client (lib/posthog/client.ts) and server (lib/posthog/server.ts) capture helpers, including graceful no-op when disabled and server client shutdown wiring.

Wires PostHog event capture across the product surface: landing/signup views; settings navigation; docs/tour interactions; template usage; workspace/table/knowledge-base activity; and broad API lifecycle events (credentials, MCP, webhooks, skills/tools, A2A agents, notifications, API keys, billing/subscription changes).

Adds execution-level analytics for workflows (success/failure, duration, block types) and expands a few endpoints to accept/propagate source metadata (e.g., API key creation from settings vs deploy modal) while keeping primary behavior unchanged.

^{Written by Cursor Bugbot for commit 531d81f. Configure here.}

[greptile-apps]

Greptile Summary

This PR instruments 48 PostHog product analytics events across the entire Sim user journey — signup, billing, workspace/workflow lifecycle, execution, blocks, knowledge bases, tables, credentials, MCP servers, custom tools, BYOK keys, A2A agents, copilot, and settings navigation. The implementation follows a clean architecture: a typed event catalog (lib/posthog/events.ts) acts as the single source of truth; a lazy singleton server client (lib/posthog/server.ts) with captureServerEvent handles all API routes; and a client helper (lib/posthog/client.ts) with captureClientEvent / captureEvent covers Zustand stores and React components respectively. All captures are fire-and-forget with no impact on self-hosted deployments.

• Typed PostHogEventMap enforces event names and property shapes at every capture site at compile time
• setOnce activation milestones (e.g. first_execution_at, first_workflow_created_at) enable cohort analysis
• $set person properties on billing events track plan state
• Group analytics (groups: { workspace }) on workspace-scoped events support workspace-level PostHog queries
• PostHog client is properly shut down on SIGTERM via instrumentation-node.ts
• All issues from previous review rounds are resolved in this commit

Confidence Score: 5/5

Safe to merge — all previously flagged P0/P1 issues are resolved, and the two remaining findings are minor P2 data-quality suggestions

All critical issues from previous review rounds are resolved: workflow_created now fires after the DB transaction, auth_method is derived from the actual provider, workflow_executed is guarded against paused status, and block add/remove tracking is clarified. The new code is entirely fire-and-forget with no production risk. The two P2 items are data-quality and style improvements that don't block merge.

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/base.tsx (passedKnowledgeBaseName in effect deps), apps/sim/app/workspace/[workspaceId]/home/components/template-prompts/template-prompts.tsx (double dynamic import pattern)

Important Files Changed

Filename	Overview
apps/sim/lib/posthog/events.ts	New typed event catalog with 48 events and strongly-typed property shapes — clean, zero runtime overhead, good single source of truth
apps/sim/lib/posthog/server.ts	Lazy singleton server client with fire-and-forget captureServerEvent; properly disabled when env vars absent; supports groups, $set, and $set_once options
apps/sim/lib/posthog/client.ts	Client helper with typed captureClientEvent (dynamic import for stores) and captureEvent (PostHog instance for React components); both safely no-op on null/failure
apps/sim/lib/workflows/executor/execute-workflow.ts	Adds workflow_executed (guarded for non-paused status) and workflow_execution_failed events with block type deduplication, duration, and workspace group analytics
apps/sim/lib/auth/auth.ts	Captures user_created in account.create.after hook; correctly derives auth_method from providerId and guards with accountCount === 1 to avoid repeat fires
apps/sim/stores/workflows/workflow/store.ts	Fires one block_added/block_removed event per unique block type in the batch via dynamic import of client helper; safe fire-and-forget pattern
apps/sim/lib/billing/webhooks/subscription.ts	Adds subscription_created (only for free→paid upgrade), subscription_cancelled (two mutually exclusive code paths), analytics wired correctly with referenceId as distinctId
apps/sim/app/workspace/[workspaceId]/knowledge/[id]/base.tsx	Adds knowledge_base_opened event; passedKnowledgeBaseName in useEffect deps can cause spurious re-fires when the name is re-fetched in the background
apps/sim/app/workspace/[workspaceId]/home/components/template-prompts/template-prompts.tsx	Adds template_used event via double dynamic import (client.ts → posthog-js); should use static import + usePostHog() pattern for React components instead
apps/sim/instrumentation-node.ts	Adds PostHog client shutdown on SIGTERM alongside existing OTel SDK shutdown; correctly awaits flush before exit

Sequence Diagram

sequenceDiagram
    participant Browser as Browser / Store
    participant API as Next.js API Route
    participant PH_Client as posthog-js (client)
    participant PH_Server as posthog-node (server)
    participant PostHog as PostHog Cloud

    Note over Browser,PostHog: Client-side events (React components)
    Browser->>PH_Client: usePostHog() → captureEvent(posthog, 'block_added', {...})
    PH_Client-->>PostHog: batch upload (async)

    Note over Browser,PostHog: Client-side events (Zustand stores)
    Browser->>Browser: import('@/lib/posthog/client')
    Browser->>PH_Client: captureClientEvent('block_added', {...})
    PH_Client-->>PostHog: batch upload (async)

    Note over API,PostHog: Server-side events (API routes)
    API->>API: captureServerEvent(userId, 'workflow_executed', props, options)
    API->>PH_Server: client.capture({ distinctId, event, properties: { ...props, $groups, $set_once } })
    PH_Server-->>PostHog: flush (flushAt=20 or flushInterval=10s)

    Note over API,PostHog: Graceful shutdown
    API->>PH_Server: getPostHogClient()?.shutdown()
    PH_Server-->>PostHog: flush remaining events

Loading

_{Reviews (10): Last reviewed commit: "fix(analytics): fix posthog in useCallba..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

Latest push adds:

• Wire remaining lifecycle events: webhook_trigger_created/deleted, workspace_deleted, notification_channel_deleted, workflow_undeployed/restored/public_api_toggled, deployment_version_activated, a2a_agent_deleted/published/unpublished, skill_created/deleted
• Add source: 'settings' | 'tool_input' to skill, custom tool, and MCP server events so we know where the action originated (settings page vs tool input dropdown)
• Track product tour: tour_started, tour_completed, tour_skipped (with tour_type: 'nav' | 'workflow' and step_index on skip)
• Track docs opened: docs_opened with source: 'help_menu' | 'editor_button' | 'toolbar_context_menu' + block_type

All server events are fire-and-forget (posthog-node queues internally). Client events use posthog?.capture() which is a synchronous enqueue — zero performance impact.

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR