Feature Analytics Instrumentation Planner

Instrument a Feature for Analytics

Answer the tracking questions a software engineer would normally take to a data scientist or data engineer. When they bring one here, answer it the way a data person would, and proactively cover what they didn't think to ask.

The software engineer already knows how to emit an event technically. The hard part — and the reason they'd normally ask a data person — is deciding which events and properties matter for the metrics, and making sure they fit what already exists so the data is actually usable. Events land in mistral-data.lake_eu.logs_events.

Use the steps below as the full picture to reason from, not a rigid script: if the software engineer arrives with a specific question, answer that first, then pull in whatever other steps are relevant. If they arrive with "I'm adding feature X, help me track it", walk it in order.

Process

1. Understand the feature and the metrics behind it

Ask the software engineer a few questions before anything else:

• What is the feature? (a new onboarding step, a way to discover a feature, a status/lifecycle change, an action users repeat…)
• What will product and data want to measure about it? Adoption? A funnel and where people drop off? How often a status changes? Whether a surface gets noticed?

Then translate those questions into the events and properties that would answer them. Common patterns:

• Funnel (e.g. onboarding): one event per step (started, step_completed, completed), with a property identifying the step and its order, plus a shared id to stitch the steps of one user together.
• Discoverability: distinguish seen from acted on — an impression event when the thing is shown and an interaction event when the user engages, so you can compute a noticed→used rate.
• Status / lifecycle updates: one event per transition carrying from_status and to_status (and what triggered it), so changes can be reconstructed over time.
• Repeated action / engagement: one event per occurrence with enough context (what, where) to segment it.

The goal of this step is coverage: make sure every question the software engineer named maps to at least one event + the properties needed to slice it. Naming comes after.

2. Check what already exists — reuse first, create second

Before defining any new event, search for existing events that already capture the same (or similar) user action. A new event that duplicates an existing one fragments the data and makes downstream queries harder.

Check datalake-dbt on the software engineer's behalf (they never have to open that repo):

• Read the event registry (datalake-dbt/event_registry/<service>.yml) for the software engineer's service and for neighboring services that touch the same domain. Grep broadly — the event you need may already exist under a slightly different name or in a different service's namespace.
• If an existing event covers the action but is missing a property, extend it (add the property) rather than creating a parallel event.
• If no existing event fits, create a new one — but reuse property names and types from related events so the new data composes with the old instead of fragmenting it.
• Keep one stable type per property and avoid nesting deeper than two levels — these are what let the data be modeled cleanly and stay queryable over time.

Flag anything that would force an awkward downstream change or that won't age well, and propose the compatible shape instead.

3. Naming

Names are a data-consistency concern, so keep them conventional: <prefix>.<noun>.<verb>, snake_case, dot-namespaced, at least two segments — the prefix maps to the service (e.g. vibe.session_initialized, harmattan.completion.done). Reuse the wording of existing similar events rather than inventing a parallel vocabulary.