Semantic conventions for events

Status: Development

This document describes the semantic conventions for Events that are represented in the data model by an EventRecord (a LogRecord with an event name).

When to define events

Events describe named occurrences at a meaningful point in time.

When to define events:

  • The occurrence does not require a new trace context or child operations.
  • The occurrence represents a checkpoint, state change, point-in-time occurrence, or outcome in a longer operation or asynchronous flow.

For example, define events for user interactions, state transitions, feature flag evaluations, lifecycle moments such as service startup, configuration reload, or shutdown completion, and exceptions that occur while an operation is being executed.

When not to define events:

  • For operations that have a duration and meaningful boundary - use spans instead.
  • For properties that describe a whole operation and do not need their own timestamp - use span attributes instead.
  • For unstructured diagnostic messages that are not intended to be queried as named events - emit regular log records instead. These records are not modeled as events, but can still follow Semantic conventions for logs.

Events often complement span definitions. Events can be emitted inside or outside an active trace context.

Use an event instead of a span attribute when the data describes a distinct occurrence within the operation, can happen zero or more times for the same span, or needs its own timestamp, severity, or occurrence-specific attributes. Use a span attribute when the data describes the operation as a whole, especially when it is useful for sampling or is known when the span starts.

An event definition should describe when the event is recorded and what domain-specific occurrence it represents in the instrumented component, the event name, which timestamp to use, the default severity, and the applicable attributes.

Event name

Semantic conventions MUST document the event name.

An event MUST have an event name that uniquely identifies the event structure.

Event names uniquely identify an event structure. When users query for a specific event name, they should get events that comply with the corresponding semantic convention.

  • Event names SHOULD follow the Naming guidelines.
  • Event names MUST NOT include dynamic values. Use attributes for identifiers, names, or other values that vary per occurrence.
  • Use a fully qualified, domain-specific name when the event is tied to a specific operation or system. For example, http.client.request.exception represents exceptions during HTTP client requests.
  • Use a shared name only when the same definition applies to all occurrences recorded with that name.
  • When modeling 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, semantic conventions can use a combination of fields to create a low-cardinality event name.

Timestamps

Events MUST have Timestamp set to the time when the event occurred.

Semantic conventions MUST NOT define a value for ObservedTimestamp; SDKs, collectors, or other components should populate it to reflect when the event was observed/received.

Severity

Semantic conventions SHOULD specify a default severity number.

Define the severity number based on the expected impact of the occurrence. If the same event can have different severity depending on context, document the conditions for setting each severity.

For exception events, follow the severity guidance in Semantic conventions for exceptions in logs.

Semantic conventions MUST NOT define a severity text.

Attributes

Semantic conventions MUST document the event attributes to represent structured event details and context:

  • Reuse existing attributes when possible, especially attributes that are used on related spans, metrics, resources, or other events.
  • Include attributes that users are likely to filter, group, aggregate, or correlate on.
  • When the event is normally associated with a span, avoid copying every span attribute by default. Reference span-level attributes on the event only when they are needed to understand, route, or retain the event without the span.
  • Prefer flat attributes when the value can be represented clearly without structure. Use complex attributes only when the structure is part of the event semantics and a flat representation would be awkward or lossy.
  • Include error.type when defining an event that represents a failure or an operation outcome that can be either success or failure.
  • Specify requirement level and tailor the brief and note to the event.
  • Document attributes that may contain sensitive information, be expensive to collect, or be especially large.

Body

Semantic conventions MUST NOT define a value for body except to represent a string display message of the event.