Semantic conventions for session

Status: Development

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

Attributes

Status:

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.

Attributes:

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

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
session.id		Required	string	The ID of the new session being started.	00112233-4455-6677-8899-aabbccddeeff
session.previous_id		Conditionally Required [1]	string	The previous session.id for this user.	00112233-4455-6677-8899-aabbccddeeff

[1] session.previous_id: If the new session is being created as a continuation of a previous session, the session.previous_id MUST 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.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
session.id		Required	string	The ID of the session being ended.	00112233-4455-6677-8899-aabbccddeeff