diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c9077e2dc5..25c9dda9999 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ release. - Move `event.domain` from InstrumentationScope attributes to LogRecord attributes. ([#2940](https://github.com/open-telemetry/opentelemetry-specification/pull/2940)) +- Split out Event API from Log API + ([#2941](https://github.com/open-telemetry/opentelemetry-specification/pull/2941)) ### Resource diff --git a/specification/logs/README.md b/specification/logs/README.md index 8a24caa0e90..cab486c6f79 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -157,8 +157,10 @@ Given the above state of the logging space we took the following approach: features than what is defined in OpenTelemetry. It is NOT a goal of OpenTelemetry to ship a feature-rich logging library. -- OpenTelemetry defines an API for [emitting Events](./api.md#emit-event). - Application developers are encouraged to call this API directly. +- OpenTelemetry defines an API for [emitting Events](./event-api.md). The API + consists of convenience methods which delegate to the API + for [emitting LogRecords](./api.md#emit-logrecord). Application developers are + encouraged to call this API directly. - OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md), which enables configuration of [processing](./sdk.md#logrecordprocessor) diff --git a/specification/logs/api.md b/specification/logs/api.md index 55fc6190c66..6ba022c4b92 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -1,4 +1,4 @@ -# Events and Logs API Interface +# Logs API Interface **Status**: [Experimental](../document-status.md) @@ -14,7 +14,6 @@ + [Get a Logger](#get-a-logger) - [Logger](#logger) * [Logger operations](#logger-operations) - + [Emit Event](#emit-event) + [Emit LogRecord](#emit-logrecord) - [LogRecord](#logrecord) - [Usage](#usage) @@ -26,20 +25,19 @@ -The Events and Logs API consist of these main classes: +The Logs API consist of these main classes: * LoggerProvider is the entry point of the API. It provides access to Loggers. * Logger is the class responsible for - creating [Events](./semantic_conventions/events.md) - and [Logs](./data-model.md#log-and-event-record-definition) as LogRecords. + emitting [Logs](./data-model.md#log-and-event-record-definition) as + LogRecords. LoggerProvider/Logger are analogous to TracerProvider/Tracer. ```mermaid graph TD A[LoggerProvider] -->|Get| B(Logger) - B --> C(Event) - B --> D(Log) + B --> C(Log) ``` ## LoggerProvider @@ -91,12 +89,9 @@ produced by this library. the scope has a version (e.g. a library version). Example value: 1.0.0. - `schema_url` (optional): Specifies the Schema URL that should be recorded in the emitted telemetry. -- `event_domain` (optional): Specifies the domain for the Events emitted, which - MUST be added as an attribute with the key `event.domain` - to [emitted Events](#emit-event). - `include_trace_context` (optional): Specifies whether the Trace Context should -automatically be passed on to the Events and Logs emitted by the Logger. This -SHOULD be true by default. + automatically be passed on to the LogRecords emitted by the Logger. This + SHOULD be true by default. - `attributes` (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. @@ -111,7 +106,7 @@ identifying fields are equal. The term *distinct* applied to Loggers describes instances where at least one identifying field has a different value. Implementations MUST NOT require users to repeatedly obtain a Logger again with -the same name+version+schema_url+event_domain+include_trace_context+attributes +the same name+version+schema_url+include_trace_context+attributes to pick up configuration changes. This can be achieved either by allowing to work with an outdated configuration or by ensuring that new configuration applies also to previously returned Loggers. @@ -120,7 +115,7 @@ Note: This could, for example, be implemented by storing any mutable configuration in the `LoggerProvider` and having `Logger` implementation objects have a reference to the `LoggerProvider` from which they were obtained. If configuration must be stored per-Logger (such as disabling a certain `Logger`), -the `Logger` could, for example, do a look-up with its name+version+schema_url+event_domain+include_trace_context+attributes +the `Logger` could, for example, do a look-up with its name+version+schema_url+include_trace_context+attributes in a map in the `LoggerProvider`, or the `LoggerProvider` could maintain a registry of all returned `Logger`s and actively update their configuration if it changes. @@ -130,7 +125,7 @@ the emitted data format is capable of representing such association. ## Logger -The `Logger` is responsible for emitting Events and Logs. +The `Logger` is responsible for emitting `LogRecord`s Note that `Logger`s should not be responsible for configuration. This should be the responsibility of the `LoggerProvider` instead. @@ -139,24 +134,6 @@ the responsibility of the `LoggerProvider` instead. The Logger MUST provide functions to: -#### Emit Event - -Emit a `LogRecord` representing an Event to the processing pipeline. - -This function MAY be named `logEvent`. - -**Parameters:** - -* `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](#logrecord) representing the Event. - -Events require the `event.domain` attribute. The API MUST not allow creating an -Event if `event_domain` was not specified when -the [Logger was obtained](#get-a-logger). - #### Emit LogRecord Emit a `LogRecord` to the processing pipeline. @@ -173,7 +150,7 @@ by end users or other instrumentation. ## LogRecord -The API emits [Events](#emit-event) and [LogRecords](#emit-logrecord) using +The API emits [LogRecords](#emit-logrecord) using the `LogRecord` [data model](data-model.md). A function receiving this as an argument MUST be able to set the following diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md new file mode 100644 index 00000000000..e8c6cbd7c05 --- /dev/null +++ b/specification/logs/event-api.md @@ -0,0 +1,69 @@ +# Events API Interface + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + + + +- [EventLogger](#eventlogger) + * [EventLogger Operations](#eventlogger-operations) + + [Create EventLogger](#create-eventlogger) + + [Emit Event](#emit-event) + + + +
+ +The Event API offers convenience methods +for [emitting LogRecords](./api.md#emit-logrecord) that conform +to the [semantic conventions for Events](./semantic_conventions/events.md). + +## EventLogger + +The `EventLogger` is the entrypoint of the Event API, and is responsible for +emitting `Events` as `LogRecords`. + +### EventLogger Operations + +The `EventLogger` MUST provide functions to: + +#### Create EventLogger + +New `EventLogger` instances are created though a constructor or factory method +on `EventLogger`. + +**Parameters:** + +* `logger` - the delegate [Logger](./api.md#logger) used to emit `Events` + as `LogRecords`. +* `event_domain` - the domain of emitted events, used to set the `event.domain` + attribute. + +#### Emit Event + +Emit a `LogRecord` representing an `Event` to the delegate `Logger`. + +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](./api.md#logrecord) representing the Event. + +**Implementation Requirements:** + +The implementation MUST [emit](./api.md#emit-logrecord) the `logRecord` to +the `logger` specified when [creating the EventLogger](#create-eventlogger) +after making the following changes: + +* 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`. diff --git a/specification/logs/img/application-api-sdk.png b/specification/logs/img/application-api-sdk.png index 988475bacdf..f302deaebb4 100644 Binary files a/specification/logs/img/application-api-sdk.png and b/specification/logs/img/application-api-sdk.png differ diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index 06a382f8eb0..1fe49af389c 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -3,8 +3,8 @@ **Status**: [Experimental](../../document-status.md) This document defines semantic conventions for recording exceptions on -[logs](../api.md#emit-logrecord) and [events](../api.md#emit-event) emitted -through the [Logger API](../api.md#logger). +[logs](../api.md#emit-logrecord) and [events](../event-api.md#emit-event) +emitted through the [Logger API](../api.md#logger).