Product events
product_event is a Bucker SDK envelope item for product analytics. It is not a Sentry item. This page is what the door does with one, the per-item answer, the caps, and what is and is not stored.
An item is accepted only for a project whose analytics gate is open (PA-01); otherwise it is refused at accept with product_category_disabled. It meters as the product category.
The accept stages
The stages run per item, in this order, and are never reordered. Each refusal writes an outcome row with its reason and appears in the per-item results array of the response. Nothing is dropped silently.
| Order | Stage | What it decides |
|---|---|---|
| 30 | reserved_names_caps |
Strips the server-owned item keys (an SDK cannot assert its own basis or claim the overflow lane). Checks the reserved-name table, the caps, and a timestamp more than 23 hours ahead of the server clock (future_timestamp). Corrects sent_at skew unless the envelope declares import mode; in import mode the event times are kept and import_id is stamped. |
| 40 | illegal_ids |
An illegal distinct_id (empty, null, undefined, anonymous, and similar) does not refuse the item: it is stored personless with illegal_distinct_id, and counted. |
| 50 | consent_basis |
Resolves the storage basis from the consent header, the project posture and the dataset rule. No acceptable basis is consent_required, or the item folds into exempt aggregates only where the register permits. |
| 70 | dedupe |
A uuid seen in the last 48 hours for the project is duplicate (outcome product_event_duplicate) and folds nothing. |
| 80 | hot_keys |
A (project, distinct id) stream above 5,000 events a minute goes to the overflow lane: no subject processing, a warning row, result accepted with warning overflow. |
Caps
| Cap | Value | Reason on breach |
|---|---|---|
| Event size | 64 KB | property_cap_exceeded |
| Properties per event | 500 | property_cap_exceeded |
| Property key | 200 characters | property_cap_exceeded |
| String value | 1 KiB | property_cap_exceeded |
| Event name | 200 characters | property_cap_exceeded |
Results
Each item of the response results array carries result (accepted, refused or duplicate), a reason and an optional warning.
| Result | Reason or warning | Meaning |
|---|---|---|
accepted |
none | Queued for the worker. |
accepted |
warning overflow |
Hot-key overflow lane; counted, no subject processing. |
accepted |
warning illegal_distinct_id |
Stored personless. |
duplicate |
product_event_duplicate |
Same uuid inside 48 hours. Folds nothing. |
refused |
property_cap_exceeded, reserved_event_name, future_timestamp, consent_required |
Not stored. One outcome row. |
The worker
The worker takes every product_event item of a job as one batch. It resolves the subject and the session, derives the actor type and traffic class, stamps the basis, then writes through the TelemetryStore seam in one transaction with the batch token. The folds (sessions, product rollups, web, interactions, flag exposures, surveys, subject properties) run inside that transaction through the fold seam; the door imports no writer.
An item that passed accept and is still unusable is poison: an invalid outcome with reason poison_event:<code>, counted, and the job completes. Only infrastructure failures raise and retry.
The product_events pillar gates the worker branch. With it off the items are accepted and metered, and the worker defers them with the reason behind pillar.
What is stored
- Folded counts in sessions and declared rollups, and the batch log (a token and counts).
- The dedupe ledger: a uuid and a day, kept for two days.
- Warning rows per project, hour, kind and event name (names past 50 in an hour file under
$other). - Outcome rows for every refusal.
What is not stored
- No raw event body, property value, raw
distinct_id, IP address or User-Agent in any table. End-user identifiers at rest are keyed pseudonyms. - The analytics lane's job payload and envelope blob are deleted when the job completes. Raw ids live for the life of the job; the seven-day retention of the durable log applies to errors only. A job that dies keeps its payload for dead-letter inspection until the ordinary prune.
Reading the warnings
GET /orgs/:orgSlug/projects/:projectSlug/product-events/warnings (project read; query windowHours, default 24, at most 14 days) returns the warning rows for the project: kind, event name, count, window.