docs: add telemetry.md with accurate description of PostHog integration (#2308)
Replaces the inaccurate opt-in framing. Documents that telemetry is on by default in the renderer, covers session recording, privacy redaction, the persistent install ID, and how to override or disable via build-time env vars. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Laxman
GitHub
parent
6a7ba46078
commit
f74ebf379f
|
|
@ -1,90 +1,35 @@
|
||||||
# Telemetry
|
# Telemetry
|
||||||
|
|
||||||
Agent Orchestrator includes telemetry for understanding product usage, reliability, and failure modes. Telemetry is implemented as **best-effort structured events** and is controlled by environment variables.
|
The Electron renderer sends anonymous usage events to PostHog automatically. The daemon is not involved.
|
||||||
|
|
||||||
## What We Collect
|
## What is collected
|
||||||
|
|
||||||
Telemetry events are structured records that capture:
|
- App activation and renderer load events
|
||||||
|
- Route views (home, project board, session detail, etc.)
|
||||||
|
- Project add / remove actions (project path is SHA-256 hashed before transmission)
|
||||||
|
- Unhandled renderer exceptions (error name and surface only)
|
||||||
|
|
||||||
- **Event Name** — The type of event (e.g., session lifecycle events, daemon operations, errors)
|
PostHog session recording is also enabled. Network request names are masked before recording.
|
||||||
- **Source** — The component that emitted the event
|
|
||||||
- **Timestamp** — When the event occurred
|
|
||||||
- **Level** — Severity level (Debug, Info, Warn, Error)
|
|
||||||
- **Context** — Project ID, Session ID, and Request ID when applicable
|
|
||||||
- **Payload** — Event-specific metadata
|
|
||||||
|
|
||||||
**We do not collect:**
|
## Privacy
|
||||||
|
|
||||||
- Code from your repositories
|
Before any event or recording is transmitted:
|
||||||
- File contents or workspace data
|
|
||||||
- Authentication credentials or API keys
|
|
||||||
- Personal information beyond what is necessary for operational analytics
|
|
||||||
|
|
||||||
## Storage and Transmission
|
- Absolute file paths (`/home/…`, `/Users/…`, `C:\…`) are replaced with `[redacted-local-path]`
|
||||||
|
- Local URLs (`file://`, `app://renderer`, `localhost`, `127.0.0.1`, `[::1]`) are replaced with `[redacted-local-url]`
|
||||||
|
- Project IDs are one-way hashed (SHA-256) and never sent in plain text
|
||||||
|
|
||||||
### Local Storage (Default)
|
## Install ID
|
||||||
|
|
||||||
By default, all telemetry events are stored locally in a SQLite database at:
|
On first run, a random install identifier is generated and stored at `~/.ao/data/telemetry_install_id` (or `$AO_DATA_DIR/telemetry_install_id`). This ID is used to deduplicate events across sessions. It is not linked to any personal account.
|
||||||
|
|
||||||
|
## Overriding the PostHog endpoint or key
|
||||||
|
|
||||||
|
The key and host are baked in at build time. To point at your own PostHog instance, set these environment variables before building:
|
||||||
|
|
||||||
```
|
```
|
||||||
~/.ao/data/telemetry.db
|
VITE_AO_POSTHOG_KEY=phc_yourkey
|
||||||
|
VITE_AO_POSTHOG_HOST=https://your-posthog-host.com
|
||||||
```
|
```
|
||||||
|
|
||||||
No data leaves your machine unless you explicitly configure remote telemetry.
|
Setting `VITE_AO_POSTHOG_KEY` to an empty string disables transmission entirely.
|
||||||
|
|
||||||
### Remote Telemetry (Opt-In)
|
|
||||||
|
|
||||||
You may optionally configure remote telemetry via PostHog by setting the `POSTHOG_API_KEY` environment variable. When configured:
|
|
||||||
|
|
||||||
- Events are transmitted to PostHog for aggregate analytics
|
|
||||||
- Transmission is best-effort — failures do not affect daemon operation
|
|
||||||
- Events are batched to minimize network overhead
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Telemetry behavior is controlled by these environment variables:
|
|
||||||
|
|
||||||
| Variable | Default | Purpose |
|
|
||||||
| -------------------- | ------------------------- | ------------------------------------------------------ |
|
|
||||||
| `AO_TELEMETRY_LEVEL` | `info` | Minimum event level to emit (debug, info, warn, error) |
|
|
||||||
| `POSTHOG_API_KEY` | unset | PostHog API key for remote telemetry |
|
|
||||||
| `POSTHOG_HOST` | `https://app.posthog.com` | PostHog host endpoint |
|
|
||||||
| `AO_DATA_DIR` | `~/.ao/data` | Directory for local telemetry database |
|
|
||||||
|
|
||||||
## Disabling Telemetry
|
|
||||||
|
|
||||||
To completely disable telemetry:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export AO_TELEMETRY_LEVEL=none
|
|
||||||
```
|
|
||||||
|
|
||||||
This prevents both local storage and any remote transmission of telemetry events.
|
|
||||||
|
|
||||||
## Event Examples
|
|
||||||
|
|
||||||
Typical telemetry events include:
|
|
||||||
|
|
||||||
- Session spawned, terminated, or restored
|
|
||||||
- Daemon started or stopped
|
|
||||||
- Agent harness lifecycle events
|
|
||||||
- HTTP request errors
|
|
||||||
- Runtime failures
|
|
||||||
- SCM observation errors
|
|
||||||
|
|
||||||
These events help us understand:
|
|
||||||
|
|
||||||
- How agents are being used
|
|
||||||
- Where failures occur
|
|
||||||
- How to improve reliability
|
|
||||||
- Which features need attention
|
|
||||||
|
|
||||||
## Privacy Commitment
|
|
||||||
|
|
||||||
- Local telemetry is stored on your machine only
|
|
||||||
- Remote telemetry is opt-in via explicit environment variable configuration
|
|
||||||
- We do not collect code, file contents, or credentials
|
|
||||||
- Events are designed for aggregate product analytics, not individual surveillance
|
|
||||||
- PostHog configuration respects your privacy settings and data retention policies
|
|
||||||
|
|
||||||
For questions or concerns about telemetry, please open an issue on GitHub or join our Discord community.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue