feat: add PostHog analytics integration

[posthog]

Summary

Adds PostHog analytics to the reference SessionExporter receiver (examples/exporter_receiver/) using the posthog Python SDK. The integration is purely additive — no existing code was removed or restructured.

• examples/exporter_receiver/config.py — new Pydantic Settings class with @lru_cache-decorated get_settings(), reading POSTHOG_PROJECT_TOKEN, POSTHOG_HOST, POSTHOG_DISABLED, and DEBUG (defaults .env via pydantic-settings)
• examples/exporter_receiver/app.py — PostHog client initialized in a FastAPI lifespan, _ph_capture() helper, and capture calls across the session lifecycle
• examples/exporter_receiver/requirements.txt — adds posthog>=3.0.0 and pydantic-settings>=2.0.0
• .gitignore — adds .env

Instrumented events:

Event	Trigger	Properties
session_started	POST /sessions	adapter_name, has_agent_id (distinct id = agent_id, falls back to session_id)
event_received	POST /sessions/{id}/events	event_type, is_orphan, adapter_name, event_count
session_ended	POST /sessions/{id}/end	events_count, evaluations_count, chain_hash_linked, had_known_session, adapter_name
schema_validation_failed	any of the three endpoints rejects on schema	endpoint, error_count (distinct id = agentegrity-receiver)

Insights and dashboards created

Type	Name	Link
Dashboard	Analytics basics (wizard)	https://us.posthog.com/project/528175/dashboard/1905021
Insight	Sessions started over time (wizard)	https://us.posthog.com/project/528175/insights/rZt535lC
Insight	Events received by type (wizard)	https://us.posthog.com/project/528175/insights/b5jn3SlR
Insight	Session lifecycle funnel (wizard)	https://us.posthog.com/project/528175/insights/LS2vcF1X
Insight	Schema validation failures by endpoint (wizard)	https://us.posthog.com/project/528175/insights/NPa8DVVc
Insight	Orphan events (wizard)	https://us.posthog.com/project/528175/insights/odq9NVZx

How to verify

1. Install the receiver deps: pip install -r examples/exporter_receiver/requirements.txt
2. Set the two environment variables from the section below (or place them in a local .env, which config.py reads via pydantic-settings).
3. Run the receiver: uvicorn examples.exporter_receiver.app:app --host 0.0.0.0 --port 8787
4. Drive a session through it (or its own tests): a POST /sessions, one or more POST /sessions/{id}/events, then POST /sessions/{id}/end.
5. In PostHog, open Activity — the session_started, event_received, and session_ended events should arrive within a minute. The wizard's dashboard populates as data lands.

To run the receiver's own test suite without sending data, leave the env vars unset — the lifespan skips client initialization when POSTHOG_PROJECT_TOKEN is absent and stays silent unless DEBUG=true:

python -m pytest examples/exporter_receiver/test_app.py

Environment variables (action needed before PostHog works)

The receiver reads its PostHog config through pydantic-settings (examples/exporter_receiver/config.py), which loads from process environment variables and, if present, a local .env file. .env is gitignored (this is a public repo and it holds the secret project token), so the real values are not committed — they must be set in whatever environment runs the receiver. There is no committed production deployment file (no Dockerfile, compose, Procfile, or hosting-provider config), so these cannot be wired automatically.

Set these in the deployment environment (or in a local .env next to the app for development):

Name	Value
POSTHOG_PROJECT_TOKEN	phc_CB2X8coGQ6k83TRRoyMcJnMRxbFr4QPzi4eD6BaAUNeo
POSTHOG_HOST	https://us.i.posthog.com

Optional:

Name	Value	Effect
POSTHOG_DISABLED	true	Skip client initialization entirely (no events sent)
DEBUG	true	Log a warning when POSTHOG_PROJECT_TOKEN is missing; silent otherwise

Add them wherever you inject runtime config for this service (compose file, systemd unit, task definition, Kubernetes secret, or hosting dashboard) and redeploy. PostHog will not receive any data until POSTHOG_PROJECT_TOKEN and POSTHOG_HOST are set.

---

Created with PostHog Code