Expand OSS telemetry emitter with ADR-0004 schema v2

README.md

@@ -244,6 +244,24 @@ make check
 
 - External dependency guide:
   [docs/external-services.md](docs/external-services.md)
+- Architecture decisions:
+  [docs/adr/README.md](docs/adr/README.md)
+
+## Telemetry
+
+Self-hosted Knowhere emits **anonymous** product telemetry to PostHog so Ontos
+operators can understand OSS adoption (install liveness, usage aggregates,
+client/document mix). Events never include filenames, prompts, emails, IPs, or
+geo. Schema and allowlists are locked in
+[ADR-0004](docs/adr/0004-anonymous-self-hosted-telemetry.md).
+
+Telemetry is **default-on**. To opt out, set:
+
+```bash
+TELEMETRY_ENABLED=false
+```
+
+Related settings live in `apps/api/.env.example` under `TELEMETRY_*`.
 
 ## Citation
 

apps/api/.env.example

@@ -30,6 +30,18 @@ TMP_PATH=/tmp/knowhere
 # Optional or development-only: observability and local dashboard wiring
 LOGFIRE_TOKEN=
 
+# Anonymous self-hosted product telemetry (PostHog). Default-on; opt out with false.
+# See docs/adr/0004-anonymous-self-hosted-telemetry.md and the README Telemetry section.
+TELEMETRY_ENABLED=true
+# TELEMETRY_POSTHOG_HOST=https://us.i.posthog.com
+# TELEMETRY_POSTHOG_PROJECT_KEY=
+# TELEMETRY_INSTALLATION_ID=
+# TELEMETRY_INSTALLATION_ID_PATH=/data/secrets/telemetry-installation-id
+# TELEMETRY_BATCH_SIZE=20
+# TELEMETRY_REQUEST_TIMEOUT_SECONDS=2.0
+# TELEMETRY_DEPLOYMENT_MODE=self_hosted
+# TELEMETRY_AGGREGATE_INTERVAL_SECONDS=300
+
 # Required for local startup: database
 DATABASE_URL=postgresql+asyncpg://root:root123@localhost:5432/Knowhere
 DB_SSL_MODE=disable

apps/api/main.py

@@ -70,10 +70,23 @@ async def lifespan(app: FastAPI):
         await load_rules(session)
     logger.info("rate limit rules loaded at startup; restart the pod to apply changes")
 
+    import time
+
     from shared.services.telemetry.aggregates import (
         start_self_hosted_aggregate_telemetry,
     )
-    from shared.services.telemetry.runtime import start_self_hosted_telemetry
+    from shared.services.telemetry.runtime import (
+        build_postgres_health_probe,
+        build_redis_health_probe,
+        start_self_hosted_heartbeat_telemetry,
+        start_self_hosted_telemetry,
+    )
+
+    telemetry_started_at = time.monotonic()
+
+    async def _redis_ping() -> bool:
+        redis_service = redis_pool_manager.get_redis_service()
+        return await redis_service.ping()
 
     telemetry_runtime = await start_self_hosted_telemetry(
         settings,
@@ -86,6 +99,7 @@ async def lifespan(app: FastAPI):
         app.state.self_hosted_telemetry_client = None
         app.state.self_hosted_telemetry_config = None
         app.state.self_hosted_aggregate_telemetry_runner = None
+        app.state.self_hosted_heartbeat_telemetry_runner = None
     else:
         telemetry_client, telemetry_config = telemetry_runtime
         app.state.self_hosted_telemetry_client = telemetry_client
@@ -99,6 +113,16 @@ async def lifespan(app: FastAPI):
                 api_metrics=app.state.self_hosted_api_telemetry_metrics,
             )
         )
+        app.state.self_hosted_heartbeat_telemetry_runner = (
+            await start_self_hosted_heartbeat_telemetry(
+                settings,
+                telemetry_client=telemetry_client,
+                config=telemetry_config,
+                started_at_monotonic=telemetry_started_at,
+                postgres_probe=build_postgres_health_probe(get_db_context),
+                redis_probe=build_redis_health_probe(_redis_ping),
+            )
+        )
 
     mcp_server = getattr(app.state, "retrieval_mcp_server", None)
     mcp_session_manager = getattr(mcp_server, "session_manager", None)
@@ -114,13 +138,20 @@ async def lifespan(app: FastAPI):
         from shared.services.telemetry.aggregates import (
             stop_self_hosted_aggregate_telemetry,
         )
-        from shared.services.telemetry.runtime import stop_self_hosted_telemetry
+        from shared.services.telemetry.runtime import (
+            stop_self_hosted_heartbeat_telemetry,
+            stop_self_hosted_telemetry,
+        )
 
+        await stop_self_hosted_heartbeat_telemetry(
+            getattr(app.state, "self_hosted_heartbeat_telemetry_runner", None)
+        )
         await stop_self_hosted_aggregate_telemetry(
             getattr(app.state, "self_hosted_aggregate_telemetry_runner", None)
         )
         await stop_self_hosted_telemetry(
-            getattr(app.state, "self_hosted_telemetry_client", None)
+            getattr(app.state, "self_hosted_telemetry_client", None),
+            config=getattr(app.state, "self_hosted_telemetry_config", None),
         )
     except Exception as e:
         logger.error(f"self-hosted telemetry shutdown failed: {e}")