feat(backend): integrate PostHog analytics for enhanced observability

[MODSetter]

• Added PostHog configuration options to .env.example files for both Docker and Surfsense backend.
• Introduced PostHog dependency in pyproject.toml.
• Implemented analytics middleware to capture various events across the application, including user authentication, automation runs, and API requests.
• Enhanced existing routes and services to emit analytics events, providing insights into user interactions and system performance.
• Ensured graceful shutdown of analytics clients in worker processes and application lifecycles.

Description

Motivation and Context

FIX #

Screenshots

API Changes

• This PR includes API changes

Change Type

• Bug fix
• New feature
• Performance improvement
• Refactoring
• Documentation
• Dependency/Build system
• Breaking change
• Other (specify):

Testing Performed

• Tested locally
• Manual/QA verification

Checklist

• Follows project coding standards and conventions
• Documentation updated as needed
• Dependencies updated as needed
• No lint/build errors or new warnings
• All relevant tests are passing

High-level PR Summary

This PR integrates PostHog analytics into the backend to provide server-side event tracking for enhanced observability. It introduces a new analytics module that captures authoritative product events (authentication, chat turns, document processing, connector operations, automations, billing, and API usage) that the frontend cannot reliably observe—especially traffic from MCP clients, PAT scripts, OAuth callbacks, and Celery background jobs. The implementation is fully opt-in (no-op when POSTHOG_API_KEY is unset), includes privacy-preserving defaults for LLM content, and is designed to be fork-safe for Celery workers. The frontend analytics were simultaneously cleaned up to remove redundant optimistic event captures, ensuring server-side events serve as the single source of truth for outcome metrics while client-side tracking focuses on user intent and UX interactions.

⏱️ Estimated Review Time: 30-90 minutes

💡 Review Order Suggestion

Order	File Path
1	surfsense_backend/pyproject.toml
2	surfsense_backend/uv.lock
3	docker/.env.example
4	surfsense_backend/.env.example
5	surfsense_backend/app/config/__init__.py
6	surfsense_backend/app/observability/__init__.py
7	surfsense_backend/app/observability/analytics.py
8	surfsense_backend/tests/unit/observability/test_analytics.py
9	surfsense_backend/app/celery_app.py
10	surfsense_backend/app/app.py
11	surfsense_backend/app/users.py
12	surfsense_backend/app/routes/anonymous_chat_routes.py
13	surfsense_backend/app/tasks/chat/streaming/flows/shared/analytics.py
14	surfsense_backend/app/tasks/chat/streaming/flows/new_chat/orchestrator.py
15	surfsense_backend/app/tasks/chat/streaming/flows/resume_chat/orchestrator.py
16	surfsense_backend/app/routes/new_chat_routes.py
17	surfsense_backend/app/routes/public_chat_routes.py
18	surfsense_backend/app/capabilities/core/access/rest.py
19	surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
20	surfsense_backend/app/routes/search_source_connectors_routes.py
21	surfsense_backend/app/tasks/celery_tasks/document_tasks.py
22	surfsense_backend/app/automations/services/automation.py
23	surfsense_backend/app/automations/services/trigger.py
24	surfsense_backend/app/automations/runtime/executor.py
25	surfsense_backend/app/routes/image_generation_routes.py
26	surfsense_backend/app/podcasts/tasks/render.py
27	surfsense_backend/app/tasks/celery_tasks/video_presentation_tasks.py
28	surfsense_backend/app/routes/rbac_routes.py
29	surfsense_backend/app/routes/incentive_tasks_routes.py
30	surfsense_backend/app/routes/stripe_routes.py
31	surfsense_backend/app/routes/workspaces_routes.py
32	surfsense_backend/app/routes/personal_access_tokens_routes.py
33	surfsense_mcp/mcp_server/core/client.py
34	surfsense_web/lib/posthog/events.ts
35	surfsense_web/app/(home)/login/LocalLoginForm.tsx
36	surfsense_web/app/(home)/register/page.tsx
37	surfsense_web/components/layout/ui/dialogs/CreateWorkspaceDialog.tsx
38	surfsense_web/app/dashboard/[workspace_id]/team/team-content.tsx
39	surfsense_web/app/invite/[invite_code]/page.tsx
40	surfsense_web/atoms/automations/automations-mutation.atoms.ts
41	surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
42	surfsense_web/components/sources/DocumentUploadTab.tsx
43	surfsense_web/lib/chat/stream-engine/engine.ts
44	surfsense_web/hooks/use-run-stream.ts
45	surfsense_web/components/settings/earn-credits-content.tsx
46	surfsense_web/lib/apis/base-api.service.ts
47	surfsense_web/content/docs/observability.mdx

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
surf-sense-frontend	Ready	Preview, Comment	Jul 23, 2026 8:20am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6c131f0-b644-4a13-bc91-556ae5561464

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev_mod

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}