diff --git a/.chloggen/events.yaml b/.chloggen/events.yaml new file mode 100644 index 0000000000..edd25c8d86 --- /dev/null +++ b/.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: diff --git a/.gitignore b/.gitignore index fdb9989733..46abe54e81 100644 --- a/.gitignore +++ b/.gitignore @@ -31,4 +31,7 @@ node_modules/ package-lock.json # Visual Studio Code -.vscode \ No newline at end of file +.vscode + +# Visual Studio +.vs/ \ No newline at end of file diff --git a/docs/general/events.md b/docs/general/events.md index d9c062a6a1..07b81ce0c4 100644 --- a/docs/general/events.md +++ b/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. + +| 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. + + +### 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. - -| 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. - - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md