diff --git a/CHANGELOG.md b/CHANGELOG.md index 83d69f366b9..b7e870da5a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Merge in the API and SDK definitions of the emitEvent from the Event API/SDK + ([#4252](https://github.com/open-telemetry/opentelemetry-specification/pull/4252)) + ### Events ### Baggage diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7b8c2b07e92..df734b3b595 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -16,7 +16,8 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) -- [Logs Instrumentation API](#logs-instrumentation-api) + * [Logs Instrumentation API](#logs-instrumentation-api) + + [Emit Event](#emit-event) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -146,13 +147,35 @@ SHOULD be documented that instrumentation authors needs to call this API each time they [emit a LogRecord](#emit-a-logrecord) to ensure they have the most up-to-date response. -## Logs Instrumentation API +### Logs Instrumentation API **Status**: [Development](../document-status.md) This set of API functions will provide the capabilities needed to emit a `LogRecord` as is currently provided by [Events API](./event-api.md). +#### Emit Event + +**Status**: [Development](../document-status.md) + +An Event is a specialized type of `LogRecord` that conforms to the +[Semantic Conventions for Events](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) +and all semantic conventions defined for logs. The effect of calling this API is +to emit a resulting OpenTelemetry `Event` to the processing pipeline as a well +formed `LogRecord`. + +**Parameters:** + +* The `Name` of the Event, as described + in [event.name semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/event.md). +* The (`AnyValue`) (optional) `Body` 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 event `Body`. +* The `Timestamp` (optional) of the Event. +* The [Context](../context/README.md) (optional) associated with the Event. +* The `SeverityNumber` (optional) of the Event. + ## Optional and required parameters The operations defined include various parameters, some of which are marked diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5212fa29a77..36b5fc4f431 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -15,6 +15,8 @@ * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Logger](#logger) + * [Logs Instrumentation API](#logs-instrumentation-api) + + [Emit Event](#emit-event) * [LoggerConfig](#loggerconfig) - [Additional LogRecord interfaces](#additional-logrecord-interfaces) * [ReadableLogRecord](#readablelogrecord) @@ -34,7 +36,6 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) -- [Logs Instrumentation API](#logs-instrumentation-api) @@ -171,6 +172,49 @@ during [logger creation](#logger-creation). If the `LoggerProvider` supports updating the [LoggerConfigurator](#loggerconfigurator), then upon update the `Logger` MUST be updated to behave according to the new `LoggerConfig`. +### Logs Instrumentation API + +**Status**: [Development](../document-status.md) + +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). + +#### Emit Event + +Emit a `LogRecord` representing an OpenTelemetry `Event` that conforms to the +definition of [Semantic Conventions for Events](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). + +**Implementation Requirements:** + +The implementation MUST use the parameters +to [emit a logRecord](./bridge-api.md#emit-a-logrecord) 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 `Body` 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 `Attributes` MUST be used to set + the [Attributes](./data-model.md#field-attributes). The user + provided `Attributes` MUST not take over the `event.name` + attribute previously discussed. +* 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. + ### LoggerConfig **Status**: [Development](../document-status.md) @@ -539,9 +583,4 @@ return a Failure result. and the destination is unavailable). [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the shutdown timeout configurable. -## Logs Instrumentation API - -> [!NOTE] -> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). - - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)