From a596f197d51c1fc373e2efa6153456123093eef5 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 Dec 2024 20:21:17 -0800 Subject: [PATCH] Deprecate `event.name` attribute in favor of EventName on the log record (#1646) --- .chloggen/1646.yaml | 4 ++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 - .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 - .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 - docs/attributes-registry/event.md | 4 +- docs/gen-ai/gen-ai-events.md | 7 ++- docs/general/events.md | 52 ++++++------------- docs/general/session.md | 4 +- docs/mobile/events.md | 2 +- model/event/common.yaml | 9 ---- .../registry-deprecated.yaml} | 8 +-- 11 files changed, 31 insertions(+), 62 deletions(-) create mode 100644 .chloggen/1646.yaml delete mode 100644 model/event/common.yaml rename model/event/{registry.yaml => deprecated/registry-deprecated.yaml} (51%) diff --git a/.chloggen/1646.yaml b/.chloggen/1646.yaml new file mode 100644 index 0000000000..778acd9c9a --- /dev/null +++ b/.chloggen/1646.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: event +note: Deprecate `event.name` attribute in favor of the top level event name property on the log record +issues: [1646] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index d65a7ffc55..43a6c3c748 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -42,7 +42,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 920ab75c84..bb0d28736a 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -34,7 +34,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index e63b412b75..eb43279195 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -43,7 +43,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md index 4489039554..7b00cb83c5 100644 --- a/docs/attributes-registry/event.md +++ b/docs/attributes-registry/event.md @@ -12,6 +12,4 @@ Attributes for Events represented using Log Records. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. +| `event.name` | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by EventName top-level field on the LogRecord | diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index 4c12ee55d5..cc77890c73 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -23,10 +23,15 @@ linkTitle: Generative AI events -GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/event-api.md). +GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event). +<<<<<<< HEAD > [!NOTE] > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language. +======= +> Note: +> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +>>>>>>> 75746bc9 (reword) Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: diff --git a/docs/general/events.md b/docs/general/events.md index 15ae55be53..c63aa5904a 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -5,7 +5,7 @@ aliases: [events-general] # Semantic Conventions for Events -**Status**: [Experimental][DocumentStatus] +**Status**: [Development][DocumentStatus] This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. @@ -15,11 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t 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 only deal with Event -semantics. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here. In addition to a required name, an Event may contain a _payload_ (body) of any type permitted by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). @@ -32,30 +28,11 @@ field semantics, and stability and requirement levels. Other events may be user- bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_ structure and semantics will also be defined. -## Event definition +## General event semantics - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. - - - - - - -### General event semantics - -* An event MUST have an `event.name` attribute that uniquely identifies the event. -* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) +* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) + that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). +* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the named event. @@ -73,21 +50,22 @@ Recommendations for defining events: collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the - [Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md) + [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) to ensure that the event is created using the configured SDK instance. - * The Event API is not yet available in all OpenTelemetry SDKs. - * TODO: Add deep link to the [compliance matrix of the Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) - when it exists. -* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `event.name` to + * The Emit Event API is not yet available in all OpenTelemetry SDKs. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `EventName` to avoid redundancy and to keep the event definition clean. * The events SHOULD document their semantic conventions including event name, attributes, and the payload. Recommendations on using attributes vs. body fields: -* If the field should be comparable across every type of record, it should be an attribute. +* If the field should be comparable across events with different `EventName` (or between an event and other telemetry items), + it should be an attribute. * If the field is specific to the event itself, then it should be a body field. -* Unless the same `event.name` exists on two events, anything in two event bodies is not comparable to each other. +* Body fields that belong to events with different event names are not comparable. + For example, body field `id` on event `my_company.order_submitted` is semantically different from + field `id` on an event with name `session.start`. ### Event payload (body) @@ -95,7 +73,7 @@ Recommendations on using attributes vs. body fields: requirements don't apply to event payload fields. * The definition for OpenTelemetry defined events supports describing individual _fields_ (Body Fields) - * The _fields_ are unique to the named event (`event.name`) and different events + * The _fields_ are unique to the named event ([EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)) and different events may use the same _field_ name to represent different data, due to the unique nature of the event. diff --git a/docs/general/session.md b/docs/general/session.md index 8302097127..18c0c447cf 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be`session.start` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be`session.start` 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, @@ -61,7 +61,7 @@ that the previous session has ended. If the session ID in `session.previous_id` ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be `session.end` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `session.end` 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 diff --git a/docs/mobile/events.md b/docs/mobile/events.md index df2e4bb7e2..e81a7da8b2 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -4,7 +4,7 @@ This document defines semantic conventions for instrumentations that emit events on mobile platforms. All mobile events MUST use a namespace of -`device` in the `event.name` property. +`device` in the EventName LogRecord property. diff --git a/model/event/common.yaml b/model/event/common.yaml deleted file mode 100644 index 8e68c5a909..0000000000 --- a/model/event/common.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: event - type: attribute_group - stability: experimental - brief: > - This document defines attributes for Events represented using Log Records. - attributes: - - ref: event.name - requirement_level: required diff --git a/model/event/registry.yaml b/model/event/deprecated/registry-deprecated.yaml similarity index 51% rename from model/event/registry.yaml rename to model/event/deprecated/registry-deprecated.yaml index c8c540e052..37f2da56b3 100644 --- a/model/event/registry.yaml +++ b/model/event/deprecated/registry-deprecated.yaml @@ -1,5 +1,5 @@ groups: - - id: registry.event + - id: registry.event.deprecated type: attribute_group display_name: Event Attributes brief: > @@ -8,11 +8,7 @@ groups: - id: event.name type: string stability: experimental + deprecated: "Replaced by EventName top-level field on the LogRecord" brief: > Identifies the class / type of event. - note: > - Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). - Notably, event names are namespaced to avoid collisions and provide a clean - separation of semantics for events in separate domains like browser, mobile, and - kubernetes. examples: ["browser.mouse.click", "device.app.lifecycle"]