Product events from annotated spans

[Makisuo]

Adds a fourth feed into product_events, alongside browser (session_events MV), server and mobile (POST /v1/events): a span the customer annotated in their own code.

span.setAttributes({
  "maple.product_event.name": "checkout_completed",  // presence is the predicate
  "maple.product_event.user_id": user.id,            // optional identity
})

That becomes a product_events row with Source='trace', carrying its TraceId/SpanId — so it steps in a funnel like any track() call and links back to the request that performed it.

Why an attribute, not a UI action

The first cut of this was going to be "mark a trace as a product event" from the trace view, backed by a Postgres annotations table. That's the wrong shape. A product event has to be emitted by the code path that performed the thing, at the moment it performed it. Marking a trace by hand marks one sampled trace, can't be replayed over history, and puts a mutable user-authored row into an append-only fact table.

An attribute marks every trace the path produces, applies retroactively across the whole traces retention window, and is reviewable in the customer's own diff. There is no new store and no write path from the dashboard: the span is the record, the product event is its projection.

Attribute selection — three tiers, one mechanism

The span's other attributes become the event's properties by default, so nothing has to be declared to get a useful event. Two optional controls narrow or replace that. Both are themselves span attributes, because a materialized view is static SQL per cluster with no per-org config to read.

"maple.product_event.include": "plan,seats"   // ONLY these span keys (whitespace trimmed)
"maple.product_event.prop.plan": "pro"        // explicit prop, merged over the base, wins ties
"maple.product_event.include": ""             // and together: full overwrite

include	prop.*	Attributes
absent	—	every span attribute
absent	set	every span attribute, props overriding on collision
"plan,seats"	—	only plan and seats
""	set	only the props

include narrows the base, prop.* merges over it, and an empty include narrows the base to nothing so only the props survive. No separate replace flag to get wrong.

Two things are load-bearing here, and both have a test pinning them:

• include switches on key presence (mapContains), not a non-empty value. A != '' would silently turn the documented overwrite back into copy-everything — the exact opposite of what the caller asked for.
• mapUpdate(base, props) argument order is the override rule. Swapped, an override gets discarded precisely when the key it meant to correct was already present.

The link

product_events gains TraceId/SpanId (DEFAULT '', appended) plus an idx_trace_id bloom filter. Real columns rather than Attributes keys because both directions filter on them, and a Map lookup on this table reads the whole map per row — the cost product_events was split out of session_events to avoid in the first place.

Direction	Query	Surface
trace → its product events	productEventsForTraceQuery	trace detail, under the anatomy strip; clicking selects the annotated span
event → the traces behind it	productEventTraceSamplesQuery	/analytics, when the event filter is set

Both panels render nothing when empty. Most traces produce no events and a browser track() call has no trace, so silence is the design rather than an empty state on every page.

Schema surfaces

All three, backfilling the trace half from traces (bounded by its 30-day retention against product_events' 365):

• BYO ClickHouse — migration 0024. requiredForIngest: false: the gateway writes neither new column, so ingest routing is not un-readied over a read-path feature.
• Managed — product_events_traces_mv, deployed with the rest of the Tinybird project.
• Local CLI — schema v13 → v14 with its migration edge.

The projection has one live definition and two frozen copies (0024 and the local edge), deliberately not sharing a constant: a delta migration describes one step in history, and a shared constant would silently rewrite what it did the next time the live projection changes.

Verified

bun typecheck green across 39 packages. Domain 662, query-engine 1366, cli 517, api 2547, web 2339 — all passing. Schema, local-manifest and Tinybird gates up to date; lint and format clean.

The Attributes expression was executed rather than assumed — mapUpdate, trimBoth and the outer-column lambda capture are all things worth checking. Against ClickHouse 26.2:

Scenario	Span attributes	Result
default	http.method, plan=free, seats=5, prop.plan=pro	{http.method, seats, plan:'pro'}
include: "plan, seats"	+ noise	{plan:'free', seats:'5'}
include: "" + prop.plan=pro	http.method, plan=free	{plan:'pro'}

Reviewer notes

The known trade. Copying the whole attribute map by default is the deliberate expensive choice: an annotated span's attributes outlive the span by a factor of twelve (365d vs 30d), and attribute pickers over product events will list the span's full semconv surface until a team sets include. The alternative — opt-in props only — was rejected because it means nothing works until you declare something. include is the lever, and it's a one-line change on the span rather than a schema migration. If this becomes the dominant cost across orgs rather than for one of them, the next lever is a per-org key denylist at the MV. Written up in docs/product-events-funnels.md.

Ingest cost. The MV predicate is one Map value read per incoming span, on the same block every other traces MV already fires on. An MV sees the insert block, not the table, so idx_span_attr_keys doesn't help it. The expensive Attributes expression only evaluates for rows that pass the WHERE, i.e. annotated spans, so its cost is per product event rather than per span.

Rollout. The managed Tinybird side of the original product-events work was never deployed — Tinybird CD is disabled and deploys are a manual operator step. This inherits that; BYO ClickHouse and local mode migrate on their own.

Not in this cut, both noted in the doc:

• No MCP tool. list_product_events still returns names only and inspect_trace doesn't surface a trace's events, so an agent can't walk the link yet. The queries and routes it would sit on exist.
• No SDK helper. Teams set the attributes by hand. A markProductEvent(span, name, { props, include }) is a wrapper over setAttributes, and it's where the empty-string overwrite idiom would get a real name instead of being a documented convention.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}