[chore] Update event semantic conventions (#880)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>

.chloggen/events.yaml

@@ -0,0 +1,22 @@
+# 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: Provides additional definitions of log events and their structure.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [ 755 ]
+
+# (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:

.gitignore

@@ -31,4 +31,7 @@ node_modules/
 package-lock.json
 
 # Visual Studio Code
-.vscode
+.vscode
+
+# Visual Studio
+.vs/

docs/general/events.md

@@ -21,9 +21,9 @@ 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_ 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`.
+In addition to a required name, an Event may contain a _payload_ (data) 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_ (data) will constitute the `Body` of the `LogRecord`.
 Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe
 the event context.
 
@@ -32,17 +32,61 @@ 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.
 
-The following semantic conventions for events are defined:
+## Event definition
 
-* **[General](#general-event-attributes): General semantic attributes that may be used in describing Events.**
-* [Exceptions](/docs/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions as events.
+<!-- semconv event -->
+| 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 names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/common/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.
+<!-- 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.31.0/specification/common#attribute)
+  attributes that provide additional context about the event.
+* It MAY contain a _payload_ (data) that describes the specific details of the
+  named event.
+* The event name uniquely identifies event structure / type of the _payload_ (data)
+  and the set of attributes.
+* The _payload_ (data) MAY contain any type supported by the OpenTelemetry data
+  model for the log [body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body)
+  and the semantic conventions will define the expected structure of the _payload_
+  (data) for the event.
+* The _payload_ (data) SHOULD be used to represent the structure of the event.
+
+Recommendations for defining events:
 
-## General event attributes
+* Use the _payload_ (data) to represent the details of the event instead of a
+  collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.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)
+    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_ (data) _fields_ with the `event.name` to
+  avoid redundancy and to keep the event definition clean.
+* The events SHOULD document their semantic conventions including event name,
+  attributes, and the payload.
 
-Events are recorded as LogRecords that are shaped in a special way: Event
-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.
+### Event payload (data)
+
+* 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
+    may use the same _field_ name to represent different data, due to the unique
+    nature of the event.
+* The _fields_ MAY reference / inherit details from the attribute registry
+  attributes and provide additional details specific to the event, including
+  providing an _alias_ (shorter) name for the attribute.
+
+## External event compatibility
 
 When recording events from an existing system as OpenTelemetry Events, it is
 possible that the existing system does not have the equivalent of a name or
@@ -52,12 +96,4 @@ such that the name identifies the event structurally. It is also recommended tha
 the event names have low-cardinality, so care must be taken to use fields
 that identify the class of Events but not the instance of the Event.
 
-<!-- semconv event -->
-| 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 names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/common/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.
-<!-- endsemconv -->
-
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md