The best way to control Claude Code, Codex and more from any computer or phone

main
md 154 lines 9.06 KB
Rendered Raw
1 # Product analytics
2
3 The server owns analytics delivery, opt-out, and identity for every connected client.
4 Clients do not load the PostHog browser SDK. Client-use events require an
5 authenticated connection, so visiting the hosted app without connecting does not
6 count as product use.
7
8 ## Installs and owners
9
10 `distinct_id` keeps the rule every build has used: the hashed Codex workspace,
11 else the Claude machine id, else the install's anonymous id. It can change when
12 someone logs in, and a Codex Team shares one, but keeping it means PostHog charts
13 and history never break. Do not change it; add a field instead.
14
15 Every event also carries `installId` when the server can save its state: the hash
16 of a random id in the state directory, which never changes for the install. If
17 that file cannot be written, events still go out under `distinct_id`, as before. Count installs
18 with it. Who an install belongs to is a separate fact, sent as
19 `install.owner_observed`. Owners are resolved at query time in our own store, so
20 a rule can change and apply to all history.
21
22 [Owner sources](../../apps/server/src/telemetry/Identify.ts), strongest first:
23 T3 Connect, then the OpenAI and Claude person ids, then the client device. The
24 server reports what it can read itself: the linked Connect account and provider
25 logins. A connecting client reports its signed-in Connect account and its device,
26 which links every environment opened from one phone, browser, or desktop. Use the
27 OpenAI `user_id` claim, not the Codex `account_id` (the ChatGPT workspace, which a
28 whole Team shares) or the token `sub` (one per login method). Two Connect accounts are never the same person, whatever
29 weaker ids they share.
30
31 Every id is SHA-256 hashed with [one helper](../../packages/shared/src/telemetryId.ts)
32 on both sides, so a Connect account hashes the same on the client and the server.
33 The server accepts only hashes from clients.
34
35 ## Attribution boundaries
36
37 Client dimensions belong to the event's WebSocket connection. A server-global
38 "current client" would misattribute simultaneous web, desktop, and mobile use.
39 Provider execution has its own events because a turn can outlive the requesting
40 connection.
41
42 Keep client and server dimensions separate. A desktop host can serve a phone or a
43 remote browser, and a direct connection can cross a network. Older clients omit
44 metadata. Missing client values must stay unknown rather than being backfilled
45 from server properties. The legacy `clientType` property describes how the server
46 runs; use `surface` for the connected client.
47
48 ## Interpreting events
49
50 Use `client.turn.requested` for active-use reports. There is no connection event,
51 because T3 Connect sessions expire hourly and each reconnect would count again.
52 A command whose id was already accepted is a retry, so it records nothing again.
53 One identity can appear in several client groups during a period; adding those
54 groups double-counts users.
55
56 Provider send and completion counts need not match. `provider.turn.completed`
57 is one provider turn, and `segment` says what started it: the run's first
58 attempt (`initial`), a `steering_restart`, a provider `continuation` such as a
59 Codex goal turn, or a `native_child` subagent. `createdBy`, `creationSource`,
60 `scheduled`, and `subagent` describe the run's starting message, and `childKind`
61 separates native subagents from T3-managed child threads. Use this event for
62 per-turn measurements, not for counting requests.
63
64 `provider.request.completed` is one run, recorded when the run settles in the
65 server process that ran it. It adds each root turn once, so continuations,
66 steering, and replayed provider events do not add rows. `requestKind: "user"`
67 counts what people asked for. Native subagent turns are summed apart from the
68 root (`childUsageStatus`, `childInputTokens`); T3-managed child threads report
69 their own requests as `t3_child`. A child still running at settlement is never
70 added later, and the summary sets `childrenRunning`. A server restart loses the
71 summary of a run in progress. A run that continues after a restart reports its
72 own usage with `restartContinuation` and `lifecycleObserved: false`; it cannot
73 recover the original request's count or kind. A run whose provider session never
74 opens has no summary, and a start the provider rejects reports
75 `providerTurns: 0`. A Stop that lands while a steering restart is starting ends
76 the run without a summary. Collection is best effort, with no scan or backfill of
77 provider history.
78
79 Counts cover the main agent. `otherInputTokens` and `otherOutputTokens` are what
80 a provider's own ledger recorded beyond it during the turn: Claude's per-process
81 `modelUsage` growth, which covers native subagents, compaction, and helper
82 calls. They need a baseline from the same process, so they stay absent when it
83 is unknown or the ledger goes backwards, and background work that ends between
84 turns lands in the next one. Claude subagents have no turns of their own, so
85 this never overlaps child turns.
86
87 `model`, `effort`, and `serviceTier` are what the run selected. `serviceTier`
88 is `standard`, `flex`, `fast`, or `ultrafast`, from Codex's tier option or
89 Claude's fast mode, and is absent when the selection does not set one. `observedModel` and
90 `mixedModels` appear only when the provider reported the models for the counted
91 work (Codex thread settings and reroutes, Claude root messages, OpenCode steps).
92 `mixedModels: false` without `reportVersion` was never checked. Model labels
93 come from the bundled model manifest and the Cursor and Grok catalogs, also for
94 routed ids such as `anthropic/claude-opus-5-5`, and efforts come from a closed
95 list, so user-configured names stay out.
96
97 Status and counters answer different questions. `usageReported: false` means
98 the adapter attached no usage; a harness where every row says so is unsupported,
99 not idle. `partial` keeps valid counts that cannot establish a whole-turn total,
100 such as an OpenCode step that ended without a report, an OpenCode stream
101 reconnect, or an interrupted segment.
102 Explicit zeros are sent and unknown counts stay absent. `localCommand` marks a
103 provider-local command such as Claude's `/compact`, whose result counters are not
104 model work. Reasoning tokens are a subset of output.
105
106 Charts built on these events should say "output tokens per measured provider
107 completion", compare matching provider, observed model, effort, interaction mode,
108 and terminal status, and show eligible and measured counts by harness, origin,
109 and status so unknown models and unsupported adapters stay in the denominator.
110 Divide summed totals for output/input ratios; averaging per-turn ratios lets
111 small-input turns dominate. Rows without `reportVersion` keep their missing
112 fields unknown; a missing origin is never a person.
113
114 `feature.used` counts WebSocket requests that start a feature. RPCs are observed in
115 the RPC authorization middleware after the request succeeds; dispatched commands
116 are recorded by the dispatch handler, which can tell a retry apart.
117 [Feature mapping](../../apps/server/src/telemetry/FeatureUsage.ts) allowlists
118 the methods and commands, and takes variants only from closed contract enums,
119 so paths, ids, and text never reach analytics. Guests of a shared thread have no
120 WebSocket connection, so the guest share service records their joins and messages
121 itself, with no `surface`.
122
123 Agent tool events report driver kinds, never instance ids: users name
124 instances, so an instance id can identify an account or employer.
125 [Provider dimensions](../../apps/server/src/telemetry/ProviderDimensions.ts)
126 report a model only when it is a non-custom entry in a vendor catalog. OpenCode,
127 Pi, and ACP agents list models from user configuration, such as local Ollama
128 tags, so their models stay out. Handoff settings come from closed enums and
129 booleans in tool arguments; prompts, titles, and ids are never read. Thread ids
130 are used only to look up the threads on each side and never leave the server,
131 which is also why tool events carry no per-thread sequence. A handoff to several
132 threads, such as `create_threads`, records one `mcp.tool.invoked` per target, each
133 repeating the call's outcome and duration, so event counts are not call counts.
134
135 ## Delivery
136
137 The server sends batches to the ingest endpoint at `ingest.t3.codes`, which archives
138 every event and forwards some of them to PostHog. A send can fail after the endpoint
139 has stored the batch, so every retry is a copy.
140 [Delivery](../../apps/server/src/telemetry/AnalyticsService.ts) gives each event a
141 uuid when it is recorded (the endpoint rejects events without one), backs off after
142 a failed send, and drops a batch after a few tries. Without these limits, one stuck
143 batch was sent every second for days.
144
145 ## Collection boundary
146
147 Keep analytics payloads to product metadata and normalized measurements. Do not
148 send prompts, authentication material, raw provider payloads, user-assigned device
149 names, or conversation identifiers. Client metadata is best effort; invalid values
150 must not reject a connection. PostHog person profiles remain disabled.
151
152 Dev-runner servers and the CI archive smoke test turn telemetry off, which also
153 stops relay tracing, because each would count as a new install. Set
154 `T3CODE_TELEMETRY_ENABLED=true` to test analytics or relay tracing from a dev server.