Deprecate event.name attribute in favor of EventName on the log record (#1646)

Author: Liudmila Molkova

.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]

.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

.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

.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

docs/attributes-registry/event.md

@@ -12,6 +12,4 @@ Attributes for Events represented using Log Records.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="event-name" href="#event-name">`event.name`</a> | 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.
+| <a id="event-name" href="#event-name">`event.name`</a> | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by EventName top-level field on the LogRecord |

docs/gen-ai/gen-ai-events.md

@@ -23,10 +23,15 @@ linkTitle: Generative AI events
 
 <!-- tocstop -->
 
-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:

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
 
-<!-- semconv event -->
-<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
-<!-- see templates/registry/markdown/snippet.md.j2 -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
-
-| 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.
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-<!-- END AUTOGENERATED TEXT -->
-<!-- endsemconv -->
-
-### 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,29 +50,30 @@ 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)
 
 * Common attribute naming conventions and [registry](../attributes-registry/README.md)
   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.
 

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

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.
 
 <!-- toc -->