From 8034c2e8cb6fa442780505022081497176f1667b Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Tue, 28 Jan 2025 15:08:15 -0800 Subject: [PATCH 01/10] add session start --- model/session/events.yaml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 model/session/events.yaml diff --git a/model/session/events.yaml b/model/session/events.yaml new file mode 100644 index 0000000000..b4a9c2eb77 --- /dev/null +++ b/model/session/events.yaml @@ -0,0 +1,26 @@ +groups: + - id: event.session.start + stability: experimental + type: event + name: session.start + brief: > + 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. From 9d4bcf721d5ecb28a073fb88aae6fd8a1c9420c8 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Tue, 28 Jan 2025 15:09:33 -0800 Subject: [PATCH 02/10] add session end --- model/session/events.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/model/session/events.yaml b/model/session/events.yaml index b4a9c2eb77..c603adfbb7 100644 --- a/model/session/events.yaml +++ b/model/session/events.yaml @@ -24,3 +24,15 @@ groups: 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: experimental + type: event + name: session.end + brief: > + 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. From 04bc6cc4887e7df9d75b467bc79aaf4262a40152 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Tue, 28 Jan 2025 15:31:56 -0800 Subject: [PATCH 03/10] fix previous_id --- model/session/events.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/session/events.yaml b/model/session/events.yaml index c603adfbb7..0e18d925c2 100644 --- a/model/session/events.yaml +++ b/model/session/events.yaml @@ -17,7 +17,7 @@ groups: - ref: session.id requirement_level: required brief: The ID of the new session being started. - - ref: session.previous.id + - ref: session.previous_id requirement_level: conditionally_required: > If the new session is being created as a continuation of a previous session, From dd9e6805d0ef2f9c5ecd01f06d836a78bc1f259e Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Tue, 28 Jan 2025 15:32:14 -0800 Subject: [PATCH 04/10] add placeholders and run markdown generation --- docs/general/session.md | 65 ++++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/general/session.md b/docs/general/session.md index 60a28e0daa..bce4c5f014 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -40,39 +40,56 @@ 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) + + + + + + + +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) + +The event name MUST be `session.start`. -[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.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 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)`. -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. +| 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) | + +**[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. + + + + + -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)`. +## 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 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) | + + + + + + -### Session End Event +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -![Experimental](https://img.shields.io/badge/-experimental-blue) +The event name MUST be `session.end`. -[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. -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) | -| 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) | + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 9e8eff4d8bef157656e8c155f10a5b2e810feb19 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Jan 2025 10:00:50 -0800 Subject: [PATCH 05/10] experimental -> development --- model/session/events.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/model/session/events.yaml b/model/session/events.yaml index 0e18d925c2..c516ac9389 100644 --- a/model/session/events.yaml +++ b/model/session/events.yaml @@ -1,6 +1,6 @@ groups: - id: event.session.start - stability: experimental + stability: development type: event name: session.start brief: > @@ -25,7 +25,7 @@ groups: attributes MUST have different values. brief: The previous `session.id` for this user, when known. - id: event.session.end - stability: experimental + stability: development type: event name: session.end brief: > From 380e1a047332a05c7acfe41de512161fb8fff002 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Jan 2025 10:29:52 -0800 Subject: [PATCH 06/10] be brief --- docs/general/session.md | 4 ++++ model/session/events.yaml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/general/session.md b/docs/general/session.md index bce4c5f014..97678e9074 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -53,6 +53,8 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve 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)`. @@ -81,6 +83,8 @@ When the `session.start` event contains both `session.id` and `session.previous_ 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 | diff --git a/model/session/events.yaml b/model/session/events.yaml index c516ac9389..edc059470c 100644 --- a/model/session/events.yaml +++ b/model/session/events.yaml @@ -4,6 +4,8 @@ groups: 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` @@ -29,6 +31,8 @@ groups: 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. From 5c7264b466bc287473da4f75c3af8ea59b6a35b2 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Jan 2025 10:39:45 -0800 Subject: [PATCH 07/10] fix anchor --- docs/general/session.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/session.md b/docs/general/session.md index 97678e9074..7a4b63e358 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-session-start) below). ## Attributes From 2db953ffcb38fdbb533de7cd1138d5b6d90f9099 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Jan 2025 10:44:11 -0800 Subject: [PATCH 08/10] markdown is hard --- docs/general/session.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/session.md b/docs/general/session.md index 7a4b63e358..4c54c69f8a 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](#event-session-start) below). +backends can link the two sessions (see [Session Start Event](#event-sessionstart) below). ## Attributes From 386a2be5172d9ff0663a31f4a12827ebe06d741a Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Jan 2025 11:05:57 -0800 Subject: [PATCH 09/10] add changelog file --- .chloggen/yamlize_session_events_1845.yaml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100755 .chloggen/yamlize_session_events_1845.yaml diff --git a/.chloggen/yamlize_session_events_1845.yaml b/.chloggen/yamlize_session_events_1845.yaml new file mode 100755 index 0000000000..6dca4f4c82 --- /dev/null +++ b/.chloggen/yamlize_session_events_1845.yaml @@ -0,0 +1,7 @@ +change_type: breaking +component: sessions +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. From 5cd6b0ad578ee78a4118c97b27464e75daa395e2 Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Wed, 29 Jan 2025 12:25:43 -0800 Subject: [PATCH 10/10] Update .chloggen/yamlize_session_events_1845.yaml Co-authored-by: Trask Stalnaker --- .chloggen/yamlize_session_events_1845.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/yamlize_session_events_1845.yaml b/.chloggen/yamlize_session_events_1845.yaml index 6dca4f4c82..cc024075de 100755 --- a/.chloggen/yamlize_session_events_1845.yaml +++ b/.chloggen/yamlize_session_events_1845.yaml @@ -1,5 +1,5 @@ change_type: breaking -component: sessions +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: >