diff --git a/CHANGELOG.md b/CHANGELOG.md index a4e37d86b02..e369eea4e90 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 diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index c543e70c035..89ed5adc31f 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,9 @@ 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` which uniquely defines a particular class or type of event. All events with the same `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). +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 @@ -74,17 +75,55 @@ 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, as described + in [event.name semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +* 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. +* 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 `event_name` MUST be set as the `event.name` attribute on the `logRecord`. +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 `Name` MUST be used to set + 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. +* 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. +* 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 `SEVERITY_NUMBER_INFO=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 + 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.