Skip to content

[events] refine general event semantics documentation #3030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Nov 20, 2025
Merged

[events] refine general event semantics documentation #3030

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
db14ce6
[events] refine general event semantics documentation
pellared Nov 4, 2025
c2c5f81
mdlint
pellared Nov 4, 2025
19ead5b
refine further
pellared Nov 4, 2025
4599186
Update event guidelines to avoid body usage
pellared Nov 4, 2025
7ff376e
Update docs/general/events.md
pellared Nov 5, 2025
6915f9c
Add missing dot
pellared Nov 5, 2025
c5eb520
Update docs/general/events.md
pellared Nov 5, 2025
512b7f2
Update docs/general/events.md
pellared Nov 7, 2025
c52b3a8
Refine event documentation and remove redundancy
pellared Nov 18, 2025
47e56bb
Merge branch 'main' into evt-refine
pellared Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions docs/general/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,31 +15,29 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t
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`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/logs/api.md) that conforms to the conventions included here.
In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.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 MUST document the event name and its attributes.

## General event semantics

* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.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.51.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.51.0/specification/logs/data-model.md#field-body) of type [`any`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.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.51.0/specification/logs/data-model.md#field-severitynumber).
* An event MUST have an [event name](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/logs/data-model.md#field-eventname)
that uniquely identifies the event structure.

It's RECOMMENDED to use the collection of attributes to represent the details of
the event.
* Event names SHOULD 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](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.0/specification/logs/data-model.md#field-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.51.0/specification/logs/data-model.md#field-body).

* Events SHOULD specify a [severity number](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.51.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