Semantic conventions for events

Status: Development

This document describes the characteristics of standalone Events that are represented in the data model by LogRecords.

Semantically, an Event is a named occurrence at an instant in time. It signals that “this thing happened at this time” and provides additional specifics about the occurrence. Examples of Events might include things like 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.

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

General event semantics

• An event MUST have an Event name property that uniquely identifies the event. Event names are subject to the Naming guidelines. Event name SHOULD be of a low-cardinality.
• Events MAY have attributes that provide additional context about the event.
• Events MAY contain a body of type any.
• The event name uniquely identifies event structure: the set of attributes and the type of the body.
• Events MAY have severity number.

It’s RECOMMENDED to use the collection of attributes to represent the details of the event.

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.