From c067af46b09989c88ac73983389ccd3963676f17 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Nov 2023 17:34:01 -0800 Subject: [PATCH 1/9] payload lives in the log body --- docs/general/events.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 8fcd24cf8a..72251a549b 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -3,13 +3,34 @@ linkTitle: Events aliases: [docs/specs/semconv/general/events-general] ---> -# Semantic Conventions for Event Attributes +# Semantic Conventions for Events **Status**: [Experimental][DocumentStatus] -This document describes the attributes of standalone Events that are represented +This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. +Semantically, an Event is a named occurrence at an instant in time. It simply signals that +"this thing happened at this time" and provides additional specifics about the occurrence. +Examples of Events might include things like uncaught exceptions, button clicks, user logout, +network connection severed, etc. + +In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to +the conventions included here, and Events +[have their own api](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). +The api abstracts away knowledge of `LogRecord` so that users are merely dealing with Event +semantics. + +In addition to a required name, an Event may contain a _payload_, which can be either structured or unstructured. +In its implementation, the Event _payload_ will constitute the `Body` of the `LogRecord`. +Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe +the event context. + +Over time, some Events will be specified by OpenTelemetry and will have documented payload structure, +field semantics, and stability and requirement levels. Other events may be user-defined and carry +bespoke user semantics. The name of the Event determines if an established payload structure is applicable +or not. + The following semantic conventions for events are defined: * **[General](#general-event-attributes): General semantic attributes that may be used in describing Events.** @@ -18,8 +39,8 @@ The following semantic conventions for events are defined: ## General event attributes Events are recorded as LogRecords that are shaped in a special way: Event -LogRecords have the attribute `event.name` that uniquely identifies the event. -Events with same `event.name` are structurally similar to one another. Events +LogRecords MUST have the attribute `event.name` that uniquely identifies the event. +Events with the same `event.name` are structurally similar to one another. Events may also have other LogRecord attributes. When recording events from an existing system as OpenTelemetry Events, it is From ec6f34229d37371593451b387221c96bfdae1e6b Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Wed, 29 Nov 2023 17:43:55 -0800 Subject: [PATCH 2/9] lint --- docs/general/events.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 72251a549b..2ee349e044 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -12,22 +12,22 @@ in the data model by `LogRecord`s. Semantically, an Event is a named occurrence at an instant in time. It simply signals that "this thing happened at this time" and provides additional specifics about the occurrence. -Examples of Events might include things like uncaught exceptions, button clicks, user logout, -network connection severed, etc. +Examples of Events might include things like uncaught exceptions, button clicks, user logout, +network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to -the conventions included here, and Events +In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to +the conventions included here, and Events [have their own api](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). The api abstracts away knowledge of `LogRecord` so that users are merely dealing with Event -semantics. +semantics. -In addition to a required name, an Event may contain a _payload_, which can be either structured or unstructured. +In addition to a required name, an Event may contain a _payload_, which can be either structured or unstructured. In its implementation, the Event _payload_ will constitute the `Body` of the `LogRecord`. Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe the event context. Over time, some Events will be specified by OpenTelemetry and will have documented payload structure, -field semantics, and stability and requirement levels. Other events may be user-defined and carry +field semantics, and stability and requirement levels. Other events may be user-defined and carry bespoke user semantics. The name of the Event determines if an established payload structure is applicable or not. From c03017243dc9a3d21486c66468ae1f94ed62297d Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Thu, 30 Nov 2023 09:21:20 -0800 Subject: [PATCH 3/9] Update docs/general/events.md Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- 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 2ee349e044..6e0d6a6f52 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` that conforms to the conventions included here, and Events -[have their own api](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). +[have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). The api abstracts away knowledge of `LogRecord` so that users are merely dealing with Event semantics. From 62e75e9f98f4fcf7f7b58fc905bacc982d136c69 Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Thu, 30 Nov 2023 09:21:39 -0800 Subject: [PATCH 4/9] Update docs/general/events.md Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- 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 6e0d6a6f52..77e69d2dc4 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -10,7 +10,7 @@ aliases: [docs/specs/semconv/general/events-general] This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. -Semantically, an Event is a named occurrence at an instant in time. It simply signals that +Semantically, an Event is a named occurrence at an instant in time. It signals that "this thing happened at this time" and provides additional specifics about the occurrence. Examples of Events might include things like uncaught exceptions, button clicks, user logout, network connection severed, etc. From edbecae507777da34160df01268d64be872f01f6 Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Thu, 30 Nov 2023 09:21:47 -0800 Subject: [PATCH 5/9] Update docs/general/events.md Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- 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 77e69d2dc4..795b362a95 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -18,7 +18,7 @@ network connection severed, etc. In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to the conventions included here, and Events [have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). -The api abstracts away knowledge of `LogRecord` so that users are merely dealing with Event +The API abstracts away knowledge of `LogRecord` so that users only deal with Event semantics. In addition to a required name, an Event may contain a _payload_, which can be either structured or unstructured. From 347f9f744f9c44c49695eba831fe1992a8e9f51f Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Fri, 1 Dec 2023 15:27:07 -0800 Subject: [PATCH 6/9] code review comments. --- docs/general/events.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 795b362a95..9478d79c60 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -21,7 +21,8 @@ the conventions included here, and Events The API abstracts away knowledge of `LogRecord` so that users only deal with Event semantics. -In addition to a required name, an Event may contain a _payload_, which can be either structured or unstructured. +In addition to a required name, an Event may contain a _payload_ of any type permitted by the +[LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). In its implementation, the Event _payload_ will constitute the `Body` of the `LogRecord`. Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe the event context. From 2428de6603b2ddd69dedc2cea3671c8d05b0f8ef Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Mon, 4 Dec 2023 15:07:49 -0800 Subject: [PATCH 7/9] update phrasing about name determining schema existence. --- docs/general/events.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 9478d79c60..51f4ef29d9 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -29,8 +29,8 @@ the event context. Over time, some Events will be specified by OpenTelemetry and will have documented payload structure, field semantics, and stability and requirement levels. Other events may be user-defined and carry -bespoke user semantics. The name of the Event determines if an established payload structure is applicable -or not. +bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_ +structure and semantics will also be defined. The following semantic conventions for events are defined: From 5bab8a711890dc6e96abcd96c4ec0126e0486f06 Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Mon, 5 Feb 2024 15:08:03 -0800 Subject: [PATCH 8/9] make some changelog yaml instead --- .chloggen/event_payload_in_body.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .chloggen/event_payload_in_body.yaml diff --git a/.chloggen/event_payload_in_body.yaml b/.chloggen/event_payload_in_body.yaml new file mode 100644 index 0000000000..f743ba580f --- /dev/null +++ b/.chloggen/event_payload_in_body.yaml @@ -0,0 +1,21 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: events + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add clarification that the body of an Event will live in the LogRecord body field. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +issues: [ '#566'] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From 34453314fa3e6ea637df9a92f4b3def8becce6ec Mon Sep 17 00:00:00 2001 From: Jason Plumb Date: Mon, 5 Feb 2024 15:09:20 -0800 Subject: [PATCH 9/9] these are ints --- .chloggen/event_payload_in_body.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/event_payload_in_body.yaml b/.chloggen/event_payload_in_body.yaml index f743ba580f..8ac0c36291 100644 --- a/.chloggen/event_payload_in_body.yaml +++ b/.chloggen/event_payload_in_body.yaml @@ -13,7 +13,7 @@ component: events note: Add clarification that the body of an Event will live in the LogRecord body field. # Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. -issues: [ '#566'] +issues: [ 566] # (Optional) One or more lines of additional information to render under the primary note. # These lines will be padded with 2 spaces and then inserted directly into the document.