diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index b117b8e132f..a6998979cff 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -81,9 +81,15 @@ This function MAY be named `logEvent`. to not override or delete this attribute while the Event is emitted to preserve its identity. * `event_data` - this argument should of type [`Attributes`](../common/README.md#attribute) - and MUST recorded as a `LogRecod` attribute with the key `event.data`. -* `other_attributes` - this argument should of type [`Attributes`](../common/README.md#attribute) - and MUST recorded as attributes on the `LogRecod`. Care MUST be taken by the + and MUST only contain the values as defined by the defined domain-specific schema + for the `event` (identified by the event domain + name combination) and is + recorded as a `LogRecod` attribute with the key `event.data`. It is optional to + support simple ping style events which do not require any form of payload, when + a payload is required `events` SHOULD provide a `event_data` and not simply use + `other_attributes` as a replacement. +* `other_attributes` - this argument is used to provide additional context about + an `event`, it should of type [`Attributes`](../common/README.md#attribute) + and MUST be recorded as attributes on the `LogRecod`. Care MUST be taken by the implementation to not override already recorded attributes with names `event.name`, `event.domain` and `event.data`. @@ -97,3 +103,10 @@ after making the following changes: when [creating the EventLogger](#create-eventlogger) MUST be set as the `event.domain` attribute on the `logRecord`. * The `event_name` MUST be set as the `event.name` attribute on the `logRecord`. +* The `event_data` if provided MUST be set as the `event.data` attribute on the + `logRecord`. Validation of the domain-specific contents of the `event_data` is + optional and not required at the API level, as validation SHOULD occur downstream + of the API. +* `other_attributes` should be optional and is only provided to enable additional + context about an `event` it is NOT a replacement for payload of an event which + is represented by the contents of `event.data`. diff --git a/specification/logs/semantic_conventions/events.md b/specification/logs/semantic_conventions/events.md index 7a1e3b07f1c..b844a340df0 100644 --- a/specification/logs/semantic_conventions/events.md +++ b/specification/logs/semantic_conventions/events.md @@ -26,27 +26,39 @@ such that the name identifies the event structurally. It is also recommended tha the event names have low-cardinality, so care must be taken to use fields that identify the class of Events but not the instance of the Event. -Events MAY include domain-specific information about the occurrence (`payload`) -of the `event`, when present this information MUST be included in the `event.data` -attribute the values included SHOULD conform to the domain-specific defined schema -for the identified `event`. This is the primary container for details about the -`event`. +The primary container for (`payload`) details describing an `event` SHOULD +include the domain-specific information about the occurrence in the `event.data` +attribute, where the definition of the values included SHOULD conform to the +domain-specific schema. The schema SHOULD be identified by the `domain` and +`name` combination. -Events MAY also include one or more additional Attributes which can be used to -provide additional context about the `event`, whether an Attribute is required -or optional SHOULD be defined by the domain-specific schema definition of the -`event`. +The `event.data` MUST only include the values as defined by it's domain-specific +schema, and if required one or more additional top-level Attributes MAY be added +to provide additional context about the `event`, but these attitional Attributes +SHOULD not be treated as a replacement for the details (`payload`) of the `event`. +For custom (Non-OpenTelemetry / User / System defined) `events` SHOULD define +their own domain-specific schema (domain + name combination) and include their +payload in the `event.data`. + +This allows a standard processing model of an `event` as represented by a `LogRecord` +so that systems MAY choose how to route, validate and/or process known `events` +based on the domain-specific schema semantic-conventions for the `event.data`. +For example, common known events MAY have special meaning or representation while +unknown events are simply treated as generic custom events. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `event.name` | string | The name identifies the event. | `click`; `exception` | Required | | `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | -| `event.data` | [any](../data-model.md#type-any) \| [map](../data-model.md#type-mapstring-any) | The domain-specific `payload` of the `event` which provides details about the occurrence of the named event. | `{ connectStart: 100, connectEnd: 103, domainLookupStart: 80, domainLookupEnd: 90 }` | Optional | +| `event.data` | [any](../data-model.md#type-any) \| [map](../data-model.md#type-mapstring-any) | The domain-specific [2] `payload` of the `event` which provides details about the occurrence of the named event. | `{ connectStart: 100, connectEnd: 103, domainLookupStart: 80, domainLookupEnd: 90 }` | Optional [3] | **[1]:** Events across different domains may have same `event.name`, yet be unrelated events. -`event.domain` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +`event.domain` has the following list of well-known values. If one of them applies, +then the respective value MUST be used, otherwise a custom value MAY be used. +To avoid clashes custom event domains SHOULD use a reversed internet domain name +style [`com.github`, `com.example`] | Value | Description | |---|---| @@ -54,10 +66,42 @@ unrelated events. | `device` | Events from mobile apps | | `k8s` | Events from Kubernetes | -`event.data` contains the domain-specific information about the occurrence of the -`event` (ie. the payload of the event). And may include details about the occurrence -or data that was change (depending on the schema of the domain-specific named event) +**[2]:** Each OpenTelemetry defined event will have it's own documented +semantic-conventions for `event.data`, while custom events SHOULD define +and document their own. + +`event.data` MUST only contain the values as defined by it's domain-specific +schema which identifies information about the occurrence of the `event` (the +`payload` of the event). Which may include details about the occurrence +or data that was changed (depending on the schema of the domain-specific named +event) The specification does not place any restriction on the fields or type of the information included in the `event.data` Attribute as it's contents SHOULD conform to the `schema` of the domain-specific event. + +**[3]:** `event.data` is optional to support simple events which do not require +any form of payload, when a payload is required `events` SHOULD define a schema +and include an `event.data` with the payload over adding a collection of top-level +general Attributes. + +## Possible Open [Experimental](../../document-status.md) Issues / Extensions + +- `event.data` schema versioning support, options include :- + - Defined at a higher OpenTelemetry level for Logs; + - Included as part of the `event.name`; + - Additional `event.schema` (Seems overkill for now); + +- User/Application provided custom data + - This is data that does not conform to any OpenTelemetry semantic conventions + and is purely user provided data that they want persisted with the event, + options include (with suggested names only):- + - Define an OpenTelemetry semantic convention Attribute for `user.data` which + would be un-validated / defined a nested Attributes (no-schema); + - Define an event specific semantic convention Attribute for `event.user_data` + which would also be an un-validated / defined nested Attributes (no-schema); + - Explicitly excluded, would be an Attribute within the `event.data` to + contain the same as this would overly complicate backend processing and could + cause a name clash within the `event.data` as some `event` schema(s) are + being defined in terms of existing external definitions (`browser`+`FetchTiming` + `event.data` is based on [W3C PerformanceResourceTiming](https://w3c.github.io/resource-timing/#sec-performanceresourcetiming) ).