The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 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. |