Skip to content

Commit 84cfd0c

Browse files
breedx-splktrasklmolkova
authored
Yamlize existing session events (open-telemetry#1845)
Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]>
1 parent 3fb5b7a commit 84cfd0c

File tree

3 files changed

+95
-25
lines changed

3 files changed

+95
-25
lines changed

‎.chloggen/yamlize_session_events_1845.yaml

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
change_type: breaking
2+
component: session
3+
note: Move `session.id` and `session.previous_id` from body fields to event attributes, and yamlize `session.start` and `session.end` events.
4+
issues: [1845]
5+
subtext: >
6+
As part of the ongoing migration of event fields from LogRecord body to extended/complex attributes, the
7+
`session.start` and `session.end` events have been redefined.

‎docs/general/session.md

+46-25
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ the Logs, Events, and Spans generated during the Session's lifecycle.
1717

1818
When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier
1919
will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry
20-
backends can link the two sessions (see [Session Start Event](#session-start-event) below).
20+
backends can link the two sessions (see [Session Start Event](#event-sessionstart) below).
2121

2222
## Attributes
2323

@@ -40,39 +40,60 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve
4040

4141
## Session Events
4242

43-
### Session Start Event
43+
## Event: `session.start`
4444

45-
![Experimental](https://img.shields.io/badge/-experimental-blue)
45+
<!-- semconv event.session.start -->
46+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
47+
<!-- see templates/registry/markdown/snippet.md.j2 -->
48+
<!-- prettier-ignore-start -->
49+
<!-- markdownlint-capture -->
50+
<!-- markdownlint-disable -->
51+
52+
**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
53+
54+
The event name MUST be `session.start`.
4655

47-
[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.0/specification/logs/data-model.md#field-eventname) MUST be`session.start`
56+
Indicates that a new session has been started, optionally linking to the prior session.
57+
58+
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.
59+
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)`.
60+
61+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
62+
|---|---|---|---|---|---|
63+
| [`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) |
64+
| [`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) |
65+
66+
**[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.
67+
68+
<!-- markdownlint-restore -->
69+
<!-- prettier-ignore-end -->
70+
<!-- END AUTOGENERATED TEXT -->
71+
<!-- endsemconv -->
4872

49-
For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted
50-
every time a session is created. When a new session is created as a continuation of a prior session,
51-
the `session.previous_id` SHOULD be included in the event. The values of `session.id` and `session.previous_id`
52-
MUST be different.
73+
## Event: `session.end`
5374

54-
When the `session.start` event contains both `session.id` and `session.previous_id` fields, the event then implies
55-
that the previous session has ended. If the session ID in `session.previous_id` has not yet ended via explicit
56-
`session.end` event, then the consumer SHOULD treat this continuation event as semantically equivalent to
57-
`session.end(session.previous_id)` and `session.start(session.id)`.
75+
<!-- semconv event.session.end -->
76+
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
77+
<!-- see templates/registry/markdown/snippet.md.j2 -->
78+
<!-- prettier-ignore-start -->
79+
<!-- markdownlint-capture -->
80+
<!-- markdownlint-disable -->
5881

59-
| Body field | Type | Description | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
60-
|---------------------------------------------------------------|--------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
61-
| [`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) |
62-
| [`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) |
82+
**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
6383

64-
### Session End Event
84+
The event name MUST be `session.end`.
6585

66-
![Experimental](https://img.shields.io/badge/-experimental-blue)
86+
Indicates that a session has ended.
6787

68-
[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.41.0/specification/logs/data-model.md#field-eventname) MUST be `session.end`
88+
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.
6989

70-
For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted
71-
every time a session ends. When a session ends and continues as a new session, this event SHOULD be
72-
emitted prior to the `session.start` event.
90+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
91+
|---|---|---|---|---|---|
92+
| [`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) |
7393

74-
| Body field | Type | Description | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
75-
|---------------------------------------------------------------|--------|----------------------------------------|--------------------------|------------------------------------------------------------------|
76-
| [`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) |
94+
<!-- markdownlint-restore -->
95+
<!-- prettier-ignore-end -->
96+
<!-- END AUTOGENERATED TEXT -->
97+
<!-- endsemconv -->
7798

7899
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

‎model/session/events.yaml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
groups:
2+
- id: event.session.start
3+
stability: development
4+
type: event
5+
name: session.start
6+
brief: >
7+
Indicates that a new session has been started, optionally linking to the prior session.
8+
note: >
9+
For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted
10+
every time a session is created. When a new session is created as a continuation of a prior session,
11+
the `session.previous_id` SHOULD be included in the event. The values of `session.id` and `session.previous_id`
12+
MUST be different.
13+
14+
When the `session.start` event contains both `session.id` and `session.previous_id` fields, the event indicates
15+
that the previous session has ended. If the session ID in `session.previous_id` has not yet ended via explicit
16+
`session.end` event, then the consumer SHOULD treat this continuation event as semantically equivalent to
17+
`session.end(session.previous_id)` and `session.start(session.id)`.
18+
attributes:
19+
- ref: session.id
20+
requirement_level: required
21+
brief: The ID of the new session being started.
22+
- ref: session.previous_id
23+
requirement_level:
24+
conditionally_required: >
25+
If the new session is being created as a continuation of a previous session,
26+
the `session.previous_id` SHOULD be included in the event. The `session.id` and `session.previous_id`
27+
attributes MUST have different values.
28+
brief: The previous `session.id` for this user, when known.
29+
- id: event.session.end
30+
stability: development
31+
type: event
32+
name: session.end
33+
brief: >
34+
Indicates that a session has ended.
35+
note: >
36+
For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted
37+
every time a session ends. When a session ends and continues as a new session, this event SHOULD be
38+
emitted prior to the `session.start` event.
39+
attributes:
40+
- ref: session.id
41+
requirement_level: required
42+
brief: The ID of the session being ended.

0 commit comments

Comments
 (0)