From 84cfd0ca4e2b148c2729c0dfc5265ee1237747a8 Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Wed, 29 Jan 2025 18:57:12 -0800 Subject: [PATCH] Yamlize existing session events (#1845) Co-authored-by: Trask Stalnaker Co-authored-by: Liudmila Molkova --- .chloggen/yamlize_session_events_1845.yaml | 7 +++ docs/general/session.md | 71 ++++++++++++++-------- model/session/events.yaml | 42 +++++++++++++ 3 files changed, 95 insertions(+), 25 deletions(-) create mode 100755 .chloggen/yamlize_session_events_1845.yaml create mode 100644 model/session/events.yaml diff --git a/.chloggen/yamlize_session_events_1845.yaml b/.chloggen/yamlize_session_events_1845.yaml new file mode 100755 index 000000000..cc024075d --- /dev/null +++ b/.chloggen/yamlize_session_events_1845.yaml @@ -0,0 +1,7 @@ +change_type: breaking +component: session +note: Move `session.id` and `session.previous_id` from body fields to event attributes, and yamlize `session.start` and `session.end` events. +issues: [1845] +subtext: > + As part of the ongoing migration of event fields from LogRecord body to extended/complex attributes, the + `session.start` and `session.end` events have been redefined. diff --git a/docs/general/session.md b/docs/general/session.md index 60a28e0da..4c54c69f8 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -17,7 +17,7 @@ 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). +backends can link the two sessions (see [Session Start Event](#event-sessionstart) below). ## Attributes @@ -40,39 +40,60 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve ## Session Events -### Session Start Event +## Event: `session.start` -![Experimental](https://img.shields.io/badge/-experimental-blue) + + + + + + -[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.0/specification/logs/data-model.md#field-eventname) MUST be`session.start` +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -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. +The event name MUST be `session.start`. -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)`. +Indicates that a new session has been started, optionally linking to the prior session. -| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `Conditionally Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +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)`. -### Session End Event +| 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 | The ID of the new session being started. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -![Experimental](https://img.shields.io/badge/-experimental-blue) +**[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. -[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.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. +## Event: `session.end` -| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) + +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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`session.id`](/docs/attributes-registry/session.md) | string | The ID of the session being ended. | `00112233-4455-6677-8899-aabbccddeeff` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/session/events.yaml b/model/session/events.yaml new file mode 100644 index 000000000..edc059470 --- /dev/null +++ b/model/session/events.yaml @@ -0,0 +1,42 @@ +groups: + - id: event.session.start + stability: development + type: event + name: session.start + brief: > + Indicates that a new session has been started, optionally linking to the prior session. + note: > + 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)`. + attributes: + - ref: session.id + requirement_level: required + brief: The ID of the new session being started. + - ref: session.previous_id + requirement_level: + conditionally_required: > + 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. + brief: The previous `session.id` for this user, when known. + - id: event.session.end + stability: development + type: event + name: session.end + brief: > + Indicates that a session has ended. + note: > + 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: + - ref: session.id + requirement_level: required + brief: The ID of the session being ended.