mirror of
https://github.com/VibedByKaKi/t3-code-android-nightly.git
synced 2026-10-10 04:11:15 +02:00
56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# Product analytics
|
|
|
|
The server owns PostHog delivery, opt-out, and identity for every connected client.
|
|
[Identity selection](../../apps/server/src/telemetry/Identify.ts) hashes an available
|
|
provider account ID, falling back to an installation-scoped ID. This identity can
|
|
span several clients; it does not identify a browser session. Clients do not load
|
|
the PostHog browser SDK. Client-use events require an authenticated connection, so
|
|
visiting the hosted app without connecting does not count as product use.
|
|
|
|
## Attribution boundaries
|
|
|
|
Client dimensions belong to the event's WebSocket connection. A server-global
|
|
"current client" would misattribute simultaneous web, desktop, and mobile use.
|
|
Provider execution has its own events because a turn can outlive the requesting
|
|
connection.
|
|
|
|
Keep client and server dimensions separate. A desktop host can serve a phone or a
|
|
remote browser, and a direct connection can cross a network. Older clients omit
|
|
metadata. Missing client values must stay unknown rather than being backfilled
|
|
from server properties. The legacy `clientType` property describes how the server
|
|
runs; use `surface` for the connected client.
|
|
|
|
## Interpreting events
|
|
|
|
Use `client.turn.requested` for active-use reports. `client.connected` counts
|
|
reconnects, so network behavior can inflate it. One identity can appear in several
|
|
client groups during a period; adding those groups double-counts users.
|
|
|
|
Provider send and completion counts need not match. Providers can emit synthetic
|
|
turns without a send request. Collection is best effort, with no scan or backfill
|
|
of provider history.
|
|
|
|
Token totals cover the main agent. Child agents and model rerouting prevent a turn
|
|
from representing one provider/model combination's full cost. For provider
|
|
comparisons, require complete usage, no observed subagents, and no mixed models;
|
|
compare matching model, effort, interaction mode, and terminal status. Aggregate
|
|
output/input ratios should divide the summed totals. Averaging per-turn ratios
|
|
lets small-input turns dominate.
|
|
|
|
Unknown counts stay absent. Partial usage contains valid observed counts but
|
|
cannot establish a whole-turn total. Keep these distinctions when changing token
|
|
normalization or building reports.
|
|
|
|
## Delivery
|
|
|
|
A send can fail after PostHog has stored the batch, so every retry is a copy.
|
|
[Delivery](../../apps/server/src/telemetry/AnalyticsService.ts) gives each event a
|
|
uuid when it is recorded, backs off after a failed send, and drops a batch after a
|
|
few tries. Without these limits, one stuck batch was sent every second for days.
|
|
|
|
## Collection boundary
|
|
|
|
Keep analytics payloads to product metadata and normalized measurements. Do not
|
|
send prompts, authentication material, raw provider payloads, user-assigned device
|
|
names, or conversation identifiers. Client metadata is best effort; invalid values
|
|
must not reject a connection. PostHog person profiles remain disabled.
|