Users, Sessions, Events, and Business Entities
An event stream mixes several kinds of entities. Treating every row as “a user action” hides important differences: events are occurrences, sessions are bounded groupings, actor identifiers are observations about identity, and business entities such as accounts or workspaces have their own lifecycles.
Prerequisites
Complete product decisions and measurement questions. Know primary keys and one-to-many relationships.
Learning goals
- State the grain and key of an event, session, actor, and business entity.
- Distinguish an anonymous identifier from a person.
- Explain why session rules are conventions rather than natural facts.
- Avoid double counting after identity resolution.
Four grains, four questions
The local JSONL fixture has one physical row per delivery attempt and an event_id for the logical event. That distinction exposes one duplicated delivery. An event is a named occurrence at occurred_at; received_at records when the measurement system observed it.
A session groups events under session_id. The fixture contains six supplied session IDs, but that does not establish a universal 30-minute rule. Mobile backgrounding, multiple tabs, offline use, and server activity can all make session boundaries product-specific. Store the rule and its version when sessions are derived rather than supplied.
anonymous_id identifies a browser or installation context, not necessarily a person. user_id identifies an account subject within this product, not necessarily a human: accounts may be shared, merged, deleted, automated, or used on many devices. The approved identity snapshot links only two anonymous IDs to known accounts. It does not infer a household or merge lookalike behavior.
Business entities answer still different questions. An account_created event says that a transition occurred; the account table would describe current or historical entity state. A workspace with five members is one workspace, five memberships, and potentially five actors. Metric grain must say which is counted.
| Entity | Example key | Grain | Typical risk |
|---|---|---|---|
| Delivery row | file line | ingestion attempt | duplicate retries |
| Event | event_id | named occurrence | ambiguous trigger |
| Session | session_id | declared activity interval | timeout sensitivity |
| Actor observation | anonymous or account ID | identity within a context | false merges/splits |
| Account | account ID | business entity | current-state leakage |
Worked example
import json
from pathlib import Path
path = Path("tests/fixtures/product-analytics/events-v1.jsonl")
events = [json.loads(line) for line in path.read_text().splitlines() if line]
known_users = {event["user_id"] for event in events if event["user_id"]}
anonymous = {event["anonymous_id"] for event in events}
sessions = {event["session_id"] for event in events}
plan = json.loads(Path("tests/fixtures/product-analytics/tracking-plan-v1.json").read_text())
print(f"rows={len(events)} unique_event_ids={len({e['event_id'] for e in events})} sessions={len(sessions)} known_users={len(known_users)}")
print(f"anonymous_ids={len(anonymous)} identity_links={len(plan['identity_snapshot']['links'])} shared_device_assumption=False")
Expected output:
rows=15 unique_event_ids=14 sessions=6 known_users=3
anonymous_ids=5 identity_links=2 shared_device_assumption=False
The counts are inventory, not yet product metrics. For example, three observed account IDs do not prove that three distinct people used the product.
Limitations and common mistakes
- Counting rows without deduplicating logical events turns delivery retries into behavior.
- Backfilling all anonymous history after login may exceed the approved purpose and changes historical results.
- Treating a session as a person overcounts multi-session actors and undercounts shared contexts.
- Joining current account state to old events can rewrite history unless the analysis explicitly wants current segmentation.
- Null
user_idmeans unresolved in this dataset; it does not mean “new user.”
Practice
Draw a grain diagram for events, actors, sessions, accounts, and workspace memberships. For “weekly active workspaces,” identify the counting key and explain why counting users or sessions would answer another question.
Next steps
Specify when each occurrence is emitted and which properties are valid in event taxonomies and tracking plans.
Primary sources
Checked 2026-10-19: OpenTelemetry Semantic Conventions 1.44.0, events and sessions; W3C, Privacy Principles: Identity on the Web.