Skip to main content

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.

EntityExample keyGrainTypical risk
Delivery rowfile lineingestion attemptduplicate retries
Eventevent_idnamed occurrenceambiguous trigger
Sessionsession_iddeclared activity intervaltimeout sensitivity
Actor observationanonymous or account IDidentity within a contextfalse merges/splits
Accountaccount IDbusiness entitycurrent-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_id means 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.