Yamlize existing session events (#1845)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

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

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
+The event name MUST be `session.start`.
-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
+Indicates that a new session has been started, optionally linking to the prior session.
-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                                                        |
+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.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
+| 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
+## Event: `session.end`
-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                                                        |
+<!-- semconv event.session.end -->
-|---------------------------------------------------------------|--------|----------------------------------------|--------------------------|------------------------------------------------------------------|
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
-| [`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) |
+<!-- 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

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.