From 6ca9c3f47f292241952607ff3a4b976757f8c06c Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 May 2024 09:48:38 -0700 Subject: [PATCH] add session start and end events --- docs/general/session.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/general/session.md b/docs/general/session.md index f8194159a0..540054d4d9 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -24,10 +24,10 @@ backends can link the two sessions (see [Session Change Event](#session-change-e -| 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` | ![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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| 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` | ![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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -35,14 +35,37 @@ backends can link the two sessions (see [Session Change Event](#session-change-e -## Session Change Event +## Session Events + +### Session Start Event ![Experimental](https://img.shields.io/badge/-experimental-blue) -When a session changes (due to time-based expiry or another mechanism), an event MAY be emitted. +`event.name`=`session.start` + +For instrumentation that tracks users 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. + +| Body field | Type | Description | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | +|---------------------------------------------------------------|--------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------| +| [`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 + +![Experimental](https://img.shields.io/badge/-experimental-blue) + +`event.name`=`session.end` + +For instrumentation that tracks users 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 also be +emitted prior to the `session.start` event. -The emitted event that represents a session change MUST have the `event.name=session.change`. -The event body MUST be empty and the attributes MUST include both the `session.id` and `session.previous_id` -attributes, as described above. The values MUST be different. +| Body field | Type | Description | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | +|---------------------------------------------------------------|--------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------| +| [`session.id`](/docs/attributes-registry/session.md) | string | The ID of the new session being started. | `Required` | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/document-status.md