Yamlize existing session events (#1845)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com> Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
2025-01-29 18:57:12 -08:00 · 2025-01-29 18:57:12 -08:00 · 84cfd0ca4e
parent 3fb5b7afcb
commit 84cfd0ca4e
3 changed files with 95 additions and 25 deletions
--- a/.chloggen/yamlize_session_events_1845.yaml
+++ 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.
--- 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)
+<!-- semconv event.session.start -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->

-[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`
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->

-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) |
+<!-- semconv event.session.end -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+**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) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->

 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
--- a/model/session/events.yaml
+++ 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.