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
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.