75 lines
5.4 KiB
Markdown
75 lines
5.4 KiB
Markdown
# Semantic conventions for session
|
|
|
|
**Status**: [Experimental][DocumentStatus]
|
|
|
|
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](#session-start-event) below).
|
|
|
|
## Attributes
|
|
|
|
<!-- semconv session-id -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`session.id`](/docs/attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |  |
|
|
| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |  |
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
## Session Events
|
|
|
|
### Session Start Event
|
|
|
|
|
|
|
|
[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be`session.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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---------------------------------------------------------------|--------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
|
|
| [`session.id`](/docs/attributes-registry/session.md) | string | The ID of the new session being started. | `Required` |  |
|
|
| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `Conditionally Required` |  |
|
|
|
|
### Session End Event
|
|
|
|
|
|
|
|
[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) 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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---------------------------------------------------------------|--------|----------------------------------------|--------------------------|------------------------------------------------------------------|
|
|
| [`session.id`](/docs/attributes-registry/session.md) | string | The ID of the new session being ended. | `Required` |  |
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|