diff --git a/docs/general/events.md b/docs/general/events.md index 63fbe0812..f86dda708 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_ (data) of any type permitted +In addition to a required name, an Event may contain a _payload_ (body) 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`. +In its implementation, the Event _payload_ (body) will constitute the `Body` of the `LogRecord`. Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe the event context. @@ -60,19 +60,19 @@ structure and semantics will also be defined. * 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.33.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 +* It MAY contain a _payload_ (body) that describes the specific details of the named event. -* The event name uniquely identifies event structure / type of the _payload_ (data) +* The event name uniquely identifies event structure / type of the _payload_ (body) and the set of attributes. -* The _payload_ (data) MAY contain any type supported by the OpenTelemetry data +* The _payload_ (body) 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. + (body) for the event. +* The _payload_ (body) SHOULD be used to represent the structure of the event. Recommendations for defining events: -* Use the _payload_ (data) to represent the details of the event instead of a +* Use the _payload_ (body) to represent the details of the event instead of a collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the @@ -81,12 +81,18 @@ Recommendations for defining events: * 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 +* It's NOT RECOMMENDED to prefix the _payload_ (body) _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. -### Event payload (data) +Recommendations on using attributes vs. body fields: + +* If the field should be comparable across every type of record, it should be an attribute. +* If the field is specific to the event itself, then it should be a body field. +* Unless the same `event.name` exists on two events, anything in two event bodies is not comparable to each other. + +### Event payload (body) * Common attribute naming conventions and [registry](../attributes-registry/README.md) requirements don't apply to event payload fields.