From db14ce610d255135952cf77a1883bcbb0fcc76a5 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Nov 2025 12:34:26 +0100 Subject: [PATCH 1/9] [events] refine general event semantics documentation --- docs/general/events.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index d4f41e4a16..2c1e19ff7c 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -22,17 +22,19 @@ with attributes and the type of the body if any. ## General event semantics -* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-eventname) - that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). Event name SHOULD be of a low-cardinality. -* Events MAY have [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) - that provide additional context about the event. -* Events MAY contain a [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body) of type [`any`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#type-any). -* The event name uniquely identifies event structure: the set of attributes and - the type of the body. -* Events MAY have [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). - -It's RECOMMENDED to use the collection of attributes to represent the details of -the event. +* An event MUST have an [event name](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-eventname) + that uniquely identifies the event structure: its [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) + and the type of the [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body). + +* Event name SHOULD be of a low-cardinality. + Event names are subject to the [Naming guidelines](/docs/general/naming.md). + +* It's RECOMMENDED to use [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) to represent the details and additional + context of the event. + +* Events SHOULD have [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber) + specified. + From c2c5f8126107f976a30e08a9b0f66fd970562f1c Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Nov 2025 12:39:11 +0100 Subject: [PATCH 2/9] mdlint --- docs/general/events.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 2c1e19ff7c..30bca68596 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -35,7 +35,6 @@ with attributes and the type of the body if any. * Events SHOULD have [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber) specified. - ## External event compatibility From 19ead5b22caf3de7f83cbaac6003d3795151dff1 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 4 Nov 2025 13:06:16 +0100 Subject: [PATCH 3/9] refine further --- docs/general/events.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 30bca68596..52dd4e0428 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -17,8 +17,7 @@ network connection severed, etc. In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/api.md) that conforms to the conventions included here. -OpenTelemetry Semantic Conventions that define events SHOULD document the event name along -with attributes and the type of the body if any. +Semantic conventions that define events SHOULD document the event name, its attributes, and the type of the body (if any). ## General event semantics @@ -26,21 +25,18 @@ with attributes and the type of the body if any. that uniquely identifies the event structure: its [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) and the type of the [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body). -* Event name SHOULD be of a low-cardinality. - Event names are subject to the [Naming guidelines](/docs/general/naming.md). +* Event names SHOULD be of low cardinality and follow the [Naming guidelines](/docs/general/naming.md). -* It's RECOMMENDED to use [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) to represent the details and additional - context of the event. +* Attributes SHOULD be used to represent details and provide additional context about the event. -* Events SHOULD have [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber) - specified. +* Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). ## External event compatibility -When recording events from an existing system as OpenTelemetry Events, the system -may lack a single name field or require multiple fields to identify the event. -In such cases, use a combination of fields to create a low-cardinality event name. +When recording events from an existing system as OpenTelemetry Events, it's common +for the system to lack a single name field or require multiple fields to identify the event. +In such cases, instrumentation SHOULD use a combination of fields to create a low-cardinality event name. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 45991864fef8c79c7d2955357238753867ae74a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 4 Nov 2025 17:45:46 +0100 Subject: [PATCH 4/9] Update event guidelines to avoid body usage Clarified guidelines on event details and body usage. --- docs/general/events.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 52dd4e0428..736e851f9b 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -29,9 +29,10 @@ Semantic conventions that define events SHOULD document the event name, its attr * Attributes SHOULD be used to represent details and provide additional context about the event. -* Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). +* Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body) + and SHOULD use attributes to provide all event details. - +* Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). ## External event compatibility From 7ff376ee4d5c3726b212d54bd87d33fbe0cc568e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Nov 2025 07:09:21 +0100 Subject: [PATCH 5/9] Update docs/general/events.md Co-authored-by: Liudmila Molkova --- docs/general/events.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 736e851f9b..a54593cbd9 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -30,7 +30,6 @@ Semantic conventions that define events SHOULD document the event name, its attr * Attributes SHOULD be used to represent details and provide additional context about the event. * Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body) - and SHOULD use attributes to provide all event details. * Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). From 6915f9c771619fa34051ea2451bb49ba39e4f16b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Nov 2025 07:11:56 +0100 Subject: [PATCH 6/9] Add missing dot --- docs/general/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index a54593cbd9..2806604e71 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -29,7 +29,7 @@ Semantic conventions that define events SHOULD document the event name, its attr * Attributes SHOULD be used to represent details and provide additional context about the event. -* Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body) +* Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body). * Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber). From c5eb5207c191c863ace350a63e2a39e10113f35d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 5 Nov 2025 17:46:45 +0100 Subject: [PATCH 7/9] Update docs/general/events.md --- docs/general/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 2806604e71..836ea5a347 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -17,7 +17,7 @@ network connection severed, etc. In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/api.md) that conforms to the conventions included here. -Semantic conventions that define events SHOULD document the event name, its attributes, and the type of the body (if any). +Semantic conventions that define events MUST document the event name, its attributes, and the type of the body (if any). ## General event semantics From 512b7f2059e16caabe88e4b9fb977acc934214f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 7 Nov 2025 07:50:54 +0100 Subject: [PATCH 8/9] Update docs/general/events.md --- docs/general/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 836ea5a347..6dccb042ae 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -25,7 +25,7 @@ Semantic conventions that define events MUST document the event name, its attrib that uniquely identifies the event structure: its [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) and the type of the [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body). -* Event names SHOULD be of low cardinality and follow the [Naming guidelines](/docs/general/naming.md). +* Event names SHOULD follow the [Naming guidelines](/docs/general/naming.md). * Attributes SHOULD be used to represent details and provide additional context about the event. From c52b3a86f4163e12b5b4c39b6aa6a7f835cc2a2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 18 Nov 2025 20:09:06 +0100 Subject: [PATCH 9/9] Refine event documentation and remove redundancy Removed redundant phrases and clarified semantic conventions for events. --- docs/general/events.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 6dccb042ae..041106d987 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -15,19 +15,20 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t Examples of Events might include things like button clicks, user logout, network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/api.md) that conforms to the conventions included here. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/api.md) +that conforms to the conventions included here. -Semantic conventions that define events MUST document the event name, its attributes, and the type of the body (if any). +Semantic conventions that define events MUST document the event name and its attributes. ## General event semantics * An event MUST have an [event name](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-eventname) - that uniquely identifies the event structure: its [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) - and the type of the [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body). + that uniquely identifies the event structure. * Event names SHOULD follow the [Naming guidelines](/docs/general/naming.md). -* Attributes SHOULD be used to represent details and provide additional context about the event. +* [Attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes) + SHOULD be used to represent details and provide additional context about the event. * Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body).