Skip to content
Merged
30 changes: 14 additions & 16 deletions docs/general/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,29 +17,27 @@ network connection severed, etc.

In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/api.md) that conforms to the conventions included here.

OpenTelemetry Semantic Conventions that define events SHOULD document the event name along
with attributes and the type of the body if any.
Semantic conventions that define events SHOULD document the event name, its attributes, and the type of the body (if any).

## General event semantics

* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-eventname)
that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). Event name SHOULD be of a low-cardinality.
* Events MAY have [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes)
that provide additional context about the event.
* Events MAY contain a [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body) of type [`any`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#type-any).
* The event name uniquely identifies event structure: the set of attributes and
the type of the body.
* Events MAY have [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber).
* An event MUST have an [event name](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-eventname)
that uniquely identifies the event structure: its [attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-attributes)
and the type of the [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body).

It's RECOMMENDED to use the collection of attributes to represent the details of
the event.
* Event names SHOULD be of low cardinality and follow the [Naming guidelines](/docs/general/naming.md).

<!-- Body use cases are not clear - see https://github.com/open-telemetry/semantic-conventions/issues/1651 for the context.-->
* Attributes SHOULD be used to represent details and provide additional context about the event.

* Events SHOULD NOT use [body](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-body)
and SHOULD use attributes to provide all event details.

* Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/logs/data-model.md#field-severitynumber).

## External event compatibility

When recording events from an existing system as OpenTelemetry Events, the system
may lack a single name field or require multiple fields to identify the event.
In such cases, use a combination of fields to create a low-cardinality event name.
When recording events from an existing system as OpenTelemetry Events, it's common
for the system to lack a single name field or require multiple fields to identify the event.
In such cases, instrumentation SHOULD use a combination of fields to create a low-cardinality event name.

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
Loading