Skip to content
bucker

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.