Semantic conventions for session

Status: Development

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

Event: session.start

Status:

The event name MUST be session.start.

Indicates that a new session has been started, optionally linking to the prior session.

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 indicates 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).

Attribute	Type	Description	Examples	Requirement Level	Stability
session.id	string	The ID of the new session being started.	00112233-4455-6677-8899-aabbccddeeff	Required
session.previous_id	string	The previous session.id for this user, when known.	00112233-4455-6677-8899-aabbccddeeff	Conditionally Required [1]

[1] session.previous_id: If the new session is being created as a continuation of a previous session, the session.previous_id SHOULD be included in the event. The session.id and session.previous_id attributes MUST have different values.

Event: session.end

Status:

The event name MUST be session.end.

Indicates that a session has ended.

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.

Attribute	Type	Description	Examples	Requirement Level	Stability
session.id	string	The ID of the session being ended.	00112233-4455-6677-8899-aabbccddeeff	Required