Add anonymous telemetry heartbeat with PostHog

[kelos-bot]

Summary

• Add internal/telemetry package that collects anonymous aggregate data (task counts, feature adoption, scale metrics, token/cost usage) and sends it to PostHog
• Add --telemetry-report, --telemetry-endpoint, and --telemetry-environment flags to the controller
• Add --disable-heartbeat flag to kelos install for opt-out
• Disable heartbeat in e2e CI
• Add telemetry documentation to docs/reference.md

Data collected

All data is anonymous aggregates — no PII, repo URLs, prompts, or secrets:

Data	Description
Installation ID	Random UUID, generated once per cluster
Kelos version	Installed controller version
Kubernetes version	Cluster K8s version
Environment	Configurable label (e.g., production, development)
Task counts	Total tasks, breakdown by type and phase
Feature adoption	Number of TaskSpawners, AgentConfigs, Workspaces, and source types in use
Scale	Number of namespaces with Kelos resources
Usage totals	Aggregate cost (USD), input tokens, and output tokens

Opting out

kelos install --disable-heartbeat

Test plan

• make verify passes
• make test passes — unit tests covering collection, sending, installation ID management, error handling, --disable-heartbeat flag, and CronJob filtering
• CI e2e tests (heartbeat disabled)

Closes #390

🤖 Generated with Claude Code

[gjkim42]

/retest

[cubic-dev-ai]

4 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/telemetry/telemetry_test.go">

<violation number="1" location="internal/telemetry/telemetry_test.go:232">
P2: Bug: `t.Fatalf` called from httptest handler goroutine. `t.Fatal`/`t.Fatalf` must only be called from the goroutine running the test. In HTTP handlers spawned by `httptest.NewServer`, use `t.Errorf` instead, or capture the error and assert it in the test goroutine.</violation>
</file>

<file name="internal/telemetry/telemetry.go">

<violation number="1" location="internal/telemetry/telemetry.go:226">
P2: The error response body is discarded, making it hard to debug telemetry send failures. Read and include the response body in the error message, and drain it on the success path for proper connection cleanup.</violation>
</file>

<file name="internal/manifests/install.yaml">

<violation number="1" location="internal/manifests/install.yaml:312">
P2: The Job template is missing `activeDeadlineSeconds`. Without it, if the telemetry collection or HTTP send hangs (e.g., API server degradation, DNS issues), the job has no upper time bound and will keep retrying up to `backoffLimit` with no per-attempt or total deadline. Consider adding `activeDeadlineSeconds: 300` (or similar) to the `jobTemplate.spec` to ensure the job is terminated if it runs too long.</violation>
</file>

<file name="cmd/kelos-controller/main.go">

<violation number="1" location="cmd/kelos-controller/main.go:97">
P2: The one-shot telemetry context has no timeout. If the Kubernetes API server is slow or unresponsive, the process could hang indefinitely. Add a context with a deadline (e.g., 2 minutes) to bound the total runtime of the telemetry report.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}