open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[chore] Add clarification on event attributes vs body fields (#1263) 

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
This commit is contained in:
Jamie Danielson 2024-07-22 11:05:50 -04:00 committed by GitHub
parent 5b640caf47
commit c0dd298edb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 16 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/general/events.md
View File

@ -21,9 +21,9 @@ the conventions included here, and Events
The API abstracts away knowledge of `LogRecord` so that users only deal with Event The API abstracts away knowledge of `LogRecord` so that users only deal with Event
semantics. 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). 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 Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe
the event context. 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. * 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) * 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. 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. 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. 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) 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_ and the semantic conventions will define the expected structure of the _payload_
(data) for the event. (body) for the event.
* The _payload_ (data) SHOULD be used to represent the structure of the event. * The _payload_ (body) SHOULD be used to represent the structure of the event.
Recommendations for defining events: 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) collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/common#attribute)
attributes. attributes.
* Events SHOULD be generated / produced / recorded using the * 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. * 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) * 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. 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. avoid redundancy and to keep the event definition clean.
* The events SHOULD document their semantic conventions including event name, * The events SHOULD document their semantic conventions including event name,
attributes, and the payload. 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) * Common attribute naming conventions and [registry](../attributes-registry/README.md)
requirements don't apply to event payload fields. requirements don't apply to event payload fields.