Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / product-telemetry-and-analytics

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]

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

TriggerConsequenceGuard
Browser analytics config is sent to a non-Cloud instanceA self-hosted or local browser can load the provider clientResolve the config only for a Cloud-managed instance with the browser switch enabled
Consent is denied or the browser sends a privacy signalBrowser capture and replay remain offResolve consent before loading or restarting the analytics client
A transaction rolls back after an event is queuedAnalytics reports a change that never became durableEmit product events through the post-commit hook
A background event omits its company scopeCloud attribution falls back to workspace-only contextWrap background emission with the entity's company and person scope
A new dimension carries customer content or a secretSensitive data leaves the application through telemetryUse only generated primitive dimensions and protected references
A batch delivery fails repeatedlySome telemetry is lost, but product work continuesUse bounded retries and log dropped batches; never make business writes depend on delivery
The browser proxy accepts an unapproved route or headerThe application becomes an open upstream proxy or leaks browser credentialsMatch fixed routes and forward an allowlisted header set

Key files

FileWhy to read it
packages/…/README.mdDefines the privacy boundary, event contract rules, Cloud delivery semantics, and retention model.
packages/…/client.tsShows the shared batching, single-sender, retry, and idempotency behavior.
packages/…/events.tsShows how product events become typed low-detail signals.
server/…/product-telemetry.tsShows when core product lifecycle events are emitted and how their dimensions are shaped.
server/…/telemetry-company-scope.tsDefines company and person attribution for request and background work.
server/…/cloud-posthog-browser.tsDefines when browser analytics is exposed and how consent context reaches the browser.
ui/…/ProductAnalyticsGate.tsxConnects session configuration, consent, delayed loading, and browser identity.
ui/…/privacy.tsDefines browser replay masking, blocked content markers, and URL redaction.
server/…/event-shape.tsShows the Cloud provider event shape, workspace grouping, and identity rules.
server/…/posthog-proxy.tsShows the narrow same-origin browser delivery boundary.
packages/…/retention.tsDefines event retention classes and windows.