Semantic conventions for session

Status: Experimental

This document defines semantic conventions to apply to client-side applications when tracking sessions.

Session is defined as the period of time encompassing all activities performed by the application and the actions executed by the end user.

Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application throughout the Session’s duration. Each Session is assigned a unique identifier, which is included as an attribute in the Logs, Events, and Spans generated during the Session’s lifecycle.

When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry backends can link the two sessions (see Session Start Event below).

Attributes

Attribute	Type	Description	Examples	Requirement Level	Stability
session.id	string	A unique id to identify a session.	00112233-4455-6677-8899-aabbccddeeff	Opt-In
session.previous_id	string	The previous session.id for this user, when known.	00112233-4455-6677-8899-aabbccddeeff	Opt-In

Session Events

Session Start Event

event.name MUST besession.start

For instrumentation that tracks user behavior during user sessions, a session.start event MUST be emitted every time a session is created. When a new session is created as a continuation of a prior session, the session.previous_id SHOULD be included in the event. The values of session.id and session.previous_id MUST be different.

When the session.start event contains both session.id and session.previous_id fields, the event then implies that the previous session has ended. If the session ID in session.previous_id has not yet ended via explicit session.end event, then the consumer SHOULD treat this continuation event as semantically equivalent to session.end(session.previous_id) and session.start(session.id).

Body field	Type	Description	Requirement Level	Stability
session.id	string	The ID of the new session being started.	Required
session.previous_id	string	The previous session.id for this user, when known.	Conditionally Required

Session End Event

event.name MUST be session.end

For instrumentation that tracks user behavior during user sessions, a session.end event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be emitted prior to the session.start event.

Body field	Type	Description	Requirement Level	Stability
session.id	string	The ID of the new session being ended.	Required