Product telemetry and analytics
Product telemetry and analytics turn selected product activity into low-detail signals for product learning and service operations. The system keeps browser analytics optional and privacy-aware, shapes server events through a shared contract, and sends each event through either the general collector or the direct Cloud provider path.
Telemetry boundary
Paperclip telemetry describes product and service outcomes rather than customer work. Its public event contract uses named events with primitive dimensions such as enums, counts, and booleans. It excludes prompts, model output, secrets, credentials, private paths, and other customer content. packages/…/README.md• L36-65 packages/…/README.md• L151-166
The main product signals cover the lifecycle of work and setup:
- task creation, completion, and blocking
- plan creation and approval
- artifact creation
- model connection
- connector lifecycle and invocation
- interaction creation and resolution
- server start and selected operational events
The shared event contract is the source of truth for event names, dimensions, optional fields, and allowed primitive values. Typed helpers keep product emitters aligned with that contract. packages/…/README.md• L16-31 packages/…/events.ts• L169-265
Browser analytics
Browser analytics is a Cloud-only product measurement path. The authenticated session receives a browser configuration only when the instance is Cloud-managed, a provider project is configured, and the browser switch is enabled. Self-hosted, local, and test instances receive no configuration and do not load the analytics client. server/…/auth.ts• L61-80 server/…/cloud-posthog-browser.ts• L1-10 server/…/cloud-posthog-config.ts• L25-42
The browser uses the same signed-in user identity as server-side Cloud events and groups activity under the Cloud workspace. It loads after the page settles or at a deadline, so analytics does not delay the first useful page state. A failed load leaves the product running without analytics. ui/…/ProductAnalyticsGate.tsx• L18-62 ui/…/product-analytics.ts• L229-283 ui/…/product-analytics.ts• L317-335
This diagram shows how the session configuration and user choice control browser delivery.
flowchart TD
A[Signed-in session] --> B{Cloud browser config?}
B -- No --> C[No browser analytics]
B -- Yes --> D[Resolve consent and browser privacy signals]
D --> E{Granted?}
E -- No --> F[Keep client off or stop capture]
E -- Yes --> G[Load analytics after page settles]
G --> H[Capture scrubbed browser events]
H --> I[Same-origin analytics proxy]
Browser consent
Consent controls browser analytics and session replay. The browser checks a server-provided requirement when available, otherwise it uses the browser time zone. A stored choice persists in browser storage. A browser-level Global Privacy Control or Do Not Track signal denies analytics when consent is required. ui/…/consent.ts• L17-67
The product settings surface lets a person grant or deny browser analytics after the initial choice. When replay is enabled, the setting states that typed content, messages, documents, and connected accounts are hidden, while page names may still appear. ui/…/ProductAnalyticsSetting.tsx• L8-43 ui/…/ProductAnalyticsGate.tsx• L64-71
References: ui/…/consent.ts• L17-67 ui/…/ProductAnalyticsSetting.tsx• L8-43 ui/…/ProductAnalyticsGate.tsx• L64-71
Browser data protection
Browser capture removes page titles and query or hash values before sending. Replay masks inputs, marked customer content, editable content, and attributes that can contain names or links. Secret elements are blocked from replay and autocapture. Autocapture records interaction structure without element text or attribute values. ui/…/privacy.ts• L15-33 ui/…/privacy.ts• L55-72 ui/…/product-analytics.ts• L142-190
The browser does not duplicate server product events. It records browser behavior and selected product journeys, such as onboarding step views and outcomes, while server telemetry records durable product changes. ui/…/product-analytics.ts• L22-24 ui/…/onboarding-analytics.ts• L4-12
References: ui/…/privacy.ts• L15-33 ui/…/privacy.ts• L55-72 ui/…/product-analytics.ts• L142-190 ui/…/onboarding-analytics.ts• L4-12
Server event shaping
Server telemetry emits only after the related database transaction commits. This ties an event to a real product change and prevents a rolled-back write from appearing in analytics. Emission is best effort: a telemetry failure is logged and does not block the product operation. server/…/product-telemetry.ts• L31-45 packages/…/README.md• L159-179
The server derives low-detail dimensions at the point of the state change. It records actor kind, coarse outcome, provider category, and work relationships without copying titles, bodies, account names, or connection data. Private references stay protected on the collector path, and private source references remain protected on every path. server/…/product-telemetry.ts• L48-66 server/…/product-telemetry.ts• L180-204 packages/…/events.ts• L11-17 packages/…/events.ts• L32-47
The telemetry client batches events and sends them through one delivery path. It uses bounded batch size and body limits, deterministic batch IDs for idempotent retries, capped backoff, and a bounded pending-retry store. Events that cannot be sent after the retry policy are dropped with an operator warning rather than blocking the application. packages/…/client.ts• L207-223 packages/…/client.ts• L261-279 packages/…/client.ts• L315-353 packages/…/config.ts• L10-24
Company scoping
Company scope keeps Cloud analytics attached to the company that produced the work. Request-bound events use the active request context. Background work has no request, so its emit site supplies the company of the reported entity before delivery. The direct transport reads this context without performing database lookups. packages/…/README.md• L225-233 server/…/telemetry-company-scope.ts• L18-38
Cloud direct events use the Cloud stack as the workspace group. When a person is known, the event also carries the company and user context and attributes the event to the request, task creator, task assigner, or run owner. When no person is known, the event remains workspace-scoped and does not create a person profile. server/…/event-shape.ts• L140-190 packages/…/README.md• L234-246
Person attribution follows a stable order for background work: task creator, task assignee, then run owner. Synthetic local identities do not become people. server/…/telemetry-company-scope.ts• L3-13 server/…/telemetry-company-scope.ts• L40-56
Delivery paths
Self-hosted installations use the default telemetry collector. Cloud can use a direct PostHog transport when the Cloud stack, project token, environment, and direct-delivery switch are valid. The client selects one sender per batch, so a batch never goes to both the collector and PostHog. server/…/telemetry.ts• L32-61 packages/…/client.ts• L97-111
The direct Cloud path keeps event names and dimensions compatible with the collector while adding Cloud identity and grouping fields. It disables GeoIP and feature flags, normalizes unknown enum values to the contract's safe fallback, and uses deterministic event identifiers to avoid duplicate counts. server/…/event-shape.ts• L100-129 server/…/event-shape.ts• L145-190
Browser traffic uses a narrow same-origin proxy. The proxy accepts only the provider routes needed by the browser client, forwards only an allowlisted header set, strips browser credentials, and applies body, concurrency, and deadline limits. It exists only when browser analytics is enabled. server/…/posthog-proxy.ts• L1-15 server/…/posthog-proxy.ts• L138-165 server/…/posthog-proxy.ts• L220-263 server/…/posthog-proxy.ts• L339-353
Retention
Telemetry retention is a data-lifecycle and query-cost policy separate from the event schema. Current first-party operational events use the operational_enum_count class and have a 90-day window because they contain only enums, booleans, counts, or coarse buckets. packages/…/retention.ts• L1-25 packages/…/retention.ts• L46-58
Retention changes do not require a schema version change. A new event must have a retention class that matches the type of data it carries. packages/…/README.md• L349-365
Direct analytics-provider integration
The direct provider integration is an adapter for Cloud delivery, not a second product event model. It mirrors the collector's event shape so existing reports continue to work while adding workspace, company, user, environment, and browser-session context where available. server/…/event-shape.ts• L12-22
On server start, Cloud also announces the workspace and sends a workspace-start event. This lets Cloud join history from the earlier collector path to the current workspace group without adding the install hash to ordinary events. server/…/transport.ts• L56-74 server/…/transport.ts• L110-141
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the generated event contract, typed helpers, retention class, and direct-provider enum fallbacks aligned.
- Keep browser and server identity rules aligned so one signed-in person does not split across analytics paths.
- Keep company context on background emitters because they do not have a live request.
- Keep privacy markers and URL scrubbing aligned with every new browser surface that can show customer content.
- Keep the browser proxy route allowlist aligned with the provider client options and disabled provider features.
- Keep post-commit emission in every writer for a tracked state transition, including direct background writers.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Browser analytics config is sent to a non-Cloud instance | A self-hosted or local browser can load the provider client | Resolve the config only for a Cloud-managed instance with the browser switch enabled |
| Consent is denied or the browser sends a privacy signal | Browser capture and replay remain off | Resolve consent before loading or restarting the analytics client |
| A transaction rolls back after an event is queued | Analytics reports a change that never became durable | Emit product events through the post-commit hook |
| A background event omits its company scope | Cloud attribution falls back to workspace-only context | Wrap background emission with the entity's company and person scope |
| A new dimension carries customer content or a secret | Sensitive data leaves the application through telemetry | Use only generated primitive dimensions and protected references |
| A batch delivery fails repeatedly | Some telemetry is lost, but product work continues | Use bounded retries and log dropped batches; never make business writes depend on delivery |
| The browser proxy accepts an unapproved route or header | The application becomes an open upstream proxy or leaks browser credentials | Match fixed routes and forward an allowlisted header set |
Key files
| File | Why to read it |
|---|---|
| packages/…/README.md | Defines the privacy boundary, event contract rules, Cloud delivery semantics, and retention model. |
| packages/…/client.ts | Shows the shared batching, single-sender, retry, and idempotency behavior. |
| packages/…/events.ts | Shows how product events become typed low-detail signals. |
| server/…/product-telemetry.ts | Shows when core product lifecycle events are emitted and how their dimensions are shaped. |
| server/…/telemetry-company-scope.ts | Defines company and person attribution for request and background work. |
| server/…/cloud-posthog-browser.ts | Defines when browser analytics is exposed and how consent context reaches the browser. |
| ui/…/ProductAnalyticsGate.tsx | Connects session configuration, consent, delayed loading, and browser identity. |
| ui/…/privacy.ts | Defines browser replay masking, blocked content markers, and URL redaction. |
| server/…/event-shape.ts | Shows the Cloud provider event shape, workspace grouping, and identity rules. |
| server/…/posthog-proxy.ts | Shows the narrow same-origin browser delivery boundary. |
| packages/…/retention.ts | Defines event retention classes and windows. |