From e077d13782874890fa1fe37df3e828f89479d085 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 17 Nov 2023 15:12:22 -0600 Subject: [PATCH 1/4] Define Event API arguments and mapping to log record --- specification/logs/event-api.md | 64 +++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 6c59ac226b3..a825fcadd0b 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -14,6 +14,7 @@ * [EventLogger Operations](#eventlogger-operations) + [Create EventLogger](#create-eventlogger) + [Emit Event](#emit-event) +- [Optional and required parameters](#optional-and-required-parameters) @@ -32,9 +33,10 @@ using the same [data model](./data-model.md). However, OpenTelemetry does recognize a subtle semantic difference between LogRecords and Events: Events are LogRecords which have a `name` and `domain`. Within a particular `domain`, the `name` uniquely defines a particular class or -type of event. Events with the same `domain` / `name` follow the same schema -which assists in analysis in observability platforms. Events are described in -more detail in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +type of event. Events with the same `domain` / `name` have `Payloads` that +conform to the same schema, which assists in analysis in observability platforms. +Events are described in more detail in +the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). While the logging space has a diverse legacy with many existing logging libraries in different languages, there is not ubiquitous alignment with @@ -76,19 +78,53 @@ This function MAY be named `logEvent`. **Parameters:** -* `event_name` - the Event name. This argument MUST be recorded as a `LogRecord` - attribute with the key `event.name`. Care MUST be taken by the implementation - to not override or delete this attribute while the Event is emitted to - preserve its identity. -* `logRecord` - the [LogRecord](./data-model.md#log-and-event-record-definition) representing the Event. +* The `Name` of the Event. +* The (`AnyValue`) `Payload` of the Event. +* The `Timestamp` (optional) of the Event. +* The [Context](../context/README.md) (optional) associated with the Event. +* The `SeverityNumber` (optional) of the Event. +* The `Attributes` (optional) of the Event. Event `Attributes` provide additional details about the Event which are not part of the well-defined `Payload`. **Implementation Requirements:** -The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to -the `logger` specified when [creating the EventLogger](#create-eventlogger) -after making the following changes: +The implementation MUST use the parameters +to [emit a logRecord](./bridge-api.md#emit-a-logrecord) using the `logger` +specified when [creating the EventLogger](#create-eventlogger) as follows: * The `event_domain` specified - 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`. + when [creating the EventLogger](#create-eventlogger) MUST be used to set + the `event.domain` [attribute](./data-model.md#field-attributes). The + implementation MUST ensure that the `event_domain` takes precedence over any + additional `Attributes` recorded with the Event. +* The `Name` MUST be used to set + the `event.name` [Attribute](./data-model.md#field-attributes). The + implementation MUST ensure that the `event.name` takes precedence over any + additional `Attributes` recorded with the Event. +* The `Payload` MUST be used to set the [Body](./data-model.md#field-body). +* If provided by the user, the `Timestamp` MUST be used to set + the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` + MUST be set to the current time when [emit](#emit-event) was called. +* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST be set + to the current time when [emit](#emit-event) was called. +* If provided by the user, the `Context` MUST be used to set + the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` + MUST be set to the current Context. +* If provided by the user, the `SeverityNumber` MUST be used to set + the [Severity Number](./data-model.md#field-severitynumber) when emitting the + logRecord. If not provided, `SeverityNumber` MUST be set to `10`. +* The [Severity Text](./data-model.md#field-severitytext) MUST not be set. +* If provided by the user, the `Attributes` MUST be used to set + the [Attributes](./data-model.md#field-attributes). The user + provided `Attributes` MUST not take over the `event.domain` and `event.name` + attributes previously discussed. + +## Optional and required parameters + +The operations defined include various parameters, some of which are marked +optional. Parameters not marked optional are required. + +For each optional parameter, the API MUST be structured to accept it, but MUST +NOT obligate a user to provide it. + +For each required parameter, the API MUST be structured to obligate a user to +provide it. From 9de29b0b9332f5bc87342bf829707e6f8900c8c9 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 17 Nov 2023 16:16:52 -0600 Subject: [PATCH 2/4] Leave ObservedTimestamp unset --- specification/logs/event-api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index a825fcadd0b..335de3bb60a 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -104,8 +104,9 @@ specified when [creating the EventLogger](#create-eventlogger) as follows: * If provided by the user, the `Timestamp` MUST be used to set the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` MUST be set to the current time when [emit](#emit-event) was called. -* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST be set - to the current time when [emit](#emit-event) was called. +* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be + set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will + set `ObservedTimestamp` to the current time when unset.) * If provided by the user, the `Context` MUST be used to set the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` MUST be set to the current Context. From dcdc90fd80e79490fc89cae43b920eff2e60ef92 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 20 Nov 2023 11:36:37 -0600 Subject: [PATCH 3/4] Optional payload, default SeverityNumber=9, reword event.name precedence --- specification/logs/event-api.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 335de3bb60a..92c914b9100 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -79,7 +79,7 @@ This function MAY be named `logEvent`. **Parameters:** * The `Name` of the Event. -* The (`AnyValue`) `Payload` of the Event. +* The (`AnyValue`) (optional) `Payload` of the Event. * The `Timestamp` (optional) of the Event. * The [Context](../context/README.md) (optional) associated with the Event. * The `SeverityNumber` (optional) of the Event. @@ -97,10 +97,12 @@ specified when [creating the EventLogger](#create-eventlogger) as follows: implementation MUST ensure that the `event_domain` takes precedence over any additional `Attributes` recorded with the Event. * The `Name` MUST be used to set - the `event.name` [Attribute](./data-model.md#field-attributes). The - implementation MUST ensure that the `event.name` takes precedence over any - additional `Attributes` recorded with the Event. -* The `Payload` MUST be used to set the [Body](./data-model.md#field-body). + the `event.name` [Attribute](./data-model.md#field-attributes). If + the `Attributes` provided by the user contain an `event.name` attribute the + value provided in the `Name` takes precedence. +* If provided by the user, the `Payload` MUST be used to set + the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be + set. * If provided by the user, the `Timestamp` MUST be used to set the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` MUST be set to the current time when [emit](#emit-event) was called. @@ -112,7 +114,7 @@ specified when [creating the EventLogger](#create-eventlogger) as follows: MUST be set to the current Context. * If provided by the user, the `SeverityNumber` MUST be used to set the [Severity Number](./data-model.md#field-severitynumber) when emitting the - logRecord. If not provided, `SeverityNumber` MUST be set to `10`. + logRecord. If not provided, `SeverityNumber` MUST be set to `9`. * The [Severity Text](./data-model.md#field-severitytext) MUST not be set. * If provided by the user, the `Attributes` MUST be used to set the [Attributes](./data-model.md#field-attributes). The user From 4d99805598fb5e0b7669a922ced7ac1efe3a4f4c Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Thu, 30 Nov 2023 13:07:48 -0600 Subject: [PATCH 4/4] Add changelog entry --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2db14f090b4..26ca5ea65a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,10 @@ release. ([#3741](https://github.com/open-telemetry/opentelemetry-specification/pull/3741)) - BREAKING: Change `event.name` definition to include `namespace` and removed `event.domain` from log event attributes. ([#3749](https://github.com/open-telemetry/opentelemetry-specification/pull/3749)) +- BREAKING: Refine the arguments of the emit Event API. Instead of accepting + a `LogRecord`, the individual arguments are enumerated along with the + implementation requirements on how those arguments map to `LogRecord`. + ([#3772](https://github.com/open-telemetry/opentelemetry-specification/pull/3772)) ### Resource