From 5d3a8a1f19f82960cf7cdc5809a19fe8f548afd3 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 12:00:40 -0700 Subject: [PATCH 01/14] expand EventLoggerProvider and EventLogger --- specification/logs/event-sdk.md | 78 +++++++++++++++++++++++++++++---- 1 file changed, 70 insertions(+), 8 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 8ebfa526a46..d2f4c6862f9 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -32,15 +32,81 @@ From OpenTelemetry's perspective LogRecords and Events are both represented using the same [data model](./event-api.md#data-model). Therefore, the default implementation of an Event SDK MUST generate events using the [Logs Data Model](./data-model.md). -The SDK MAY be implemented on top of the [Logs Bridge API](./bridge-api.md). +The SDK MUST use the default [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. ## EventLoggerProvider -TODO +The `EventLoggerProvider` MUST be implemented as a proxy to an instance of `LoggerProvider`. -## EventLogger +All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SHOULD be associated with the `Resource` from the provided `LoggerProvider`. + +### EventLoggerProvider Creation + +The SDK SHOULD allow the creation of multiple independent `EventLoggerProviders`s. + +### EventLogger Creation + +It SHOULD only be possible to create `EventLogger` instances through a `EventLoggerProvider` +(see [Events API](event-api.md)). + +The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). + +The input provided by the user MUST be used to create +an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which +is associated with `Event`s emitted by the created `EventLogger`. + +In the case where an invalid `name` (null or empty string) is specified, a +working `EventLogger` MUST be returned as a fallback rather than returning null or +throwing an exception. Its `name` SHOULD keep the original invalid value, and a +message reporting that the specified value is invalid SHOULD be logged. + +### Configuration + +The `EventLoggerProvider` MUST accept an instance of `LoggerProvider`. Any configuration +related to processing MUST be done by configuring the `LoggerProvider` directly. + +### Shutdown + +This method provides a way for provider to do any cleanup required. -TODO +`Shutdown` MUST be called only once for each `EventLoggerProvider` instance. After +the call to `Shutdown`, subsequent attempts to get an `EventLogger` are not allowed. +SDKs SHOULD return a valid no-op `EventLogger` for these calls, if possible. + +`Shutdown` SHOULD provide a way to let the caller know whether it succeeded, +failed or timed out. + +`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` MAY be +implemented as a blocking API or an asynchronous API which notifies the caller +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY +decide if they want to make the shutdown timeout configurable. + +`Shutdown` MUST be implemented at least by invoking `Shutdown` on the delegate +`LoggerProvider`, which in effect invokes `Shutdown` on all registered +registered [LogRecordProcessors](#logrecordprocessor). + +### ForceFlush + +This method provides a way for the provider to notify the delegate `LoggerProvider` +to force all registered [LogRecordProcessors](#logrecordprocessor) to immediately export all +`LogRecords` that have not yet been exported. + +`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, +failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there +is an error condition; and if there is no error condition, it SHOULD return +some **NO ERROR** status, language implementations MAY decide how to model +**ERROR** and **NO ERROR**. + +`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` MAY be +implemented as a blocking API or an asynchronous API which notifies the caller +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY +decide if they want to make the flush timeout configurable. + +`ForceFlush` MUST invoke `ForceFlush` on all +[LogRecordProcessors](#logrecordprocessor) that are registered with the delegate +`LoggerProvider`. + +## EventLogger ### Emit Event @@ -76,7 +142,3 @@ to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: the [Attributes](./data-model.md#field-attributes). The user provided `Attributes` MUST not take over the `event.name` attribute previously discussed. - -## Additional Interfaces - -TODO From 2b27f3058bc4f5704c56d7a56076c42d9bf6af00 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 12:24:12 -0700 Subject: [PATCH 02/14] simplified shutdown and forceflush sections --- specification/logs/event-sdk.md | 33 +-------------------------------- 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index d2f4c6862f9..0a6da15bba4 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -32,7 +32,7 @@ From OpenTelemetry's perspective LogRecords and Events are both represented using the same [data model](./event-api.md#data-model). Therefore, the default implementation of an Event SDK MUST generate events using the [Logs Data Model](./data-model.md). -The SDK MUST use the default [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. +The SDK MUST use the [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. ## EventLoggerProvider @@ -51,10 +51,6 @@ It SHOULD only be possible to create `EventLogger` instances through a `EventLog The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). -The input provided by the user MUST be used to create -an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which -is associated with `Event`s emitted by the created `EventLogger`. - In the case where an invalid `name` (null or empty string) is specified, a working `EventLogger` MUST be returned as a fallback rather than returning null or throwing an exception. Its `name` SHOULD keep the original invalid value, and a @@ -69,18 +65,6 @@ related to processing MUST be done by configuring the `LoggerProvider` directly. This method provides a way for provider to do any cleanup required. -`Shutdown` MUST be called only once for each `EventLoggerProvider` instance. After -the call to `Shutdown`, subsequent attempts to get an `EventLogger` are not allowed. -SDKs SHOULD return a valid no-op `EventLogger` for these calls, if possible. - -`Shutdown` SHOULD provide a way to let the caller know whether it succeeded, -failed or timed out. - -`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` MAY be -implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY -decide if they want to make the shutdown timeout configurable. - `Shutdown` MUST be implemented at least by invoking `Shutdown` on the delegate `LoggerProvider`, which in effect invokes `Shutdown` on all registered registered [LogRecordProcessors](#logrecordprocessor). @@ -91,21 +75,6 @@ This method provides a way for the provider to notify the delegate `LoggerProvid to force all registered [LogRecordProcessors](#logrecordprocessor) to immediately export all `LogRecords` that have not yet been exported. -`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, -failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there -is an error condition; and if there is no error condition, it SHOULD return -some **NO ERROR** status, language implementations MAY decide how to model -**ERROR** and **NO ERROR**. - -`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` MAY be -implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY -decide if they want to make the flush timeout configurable. - -`ForceFlush` MUST invoke `ForceFlush` on all -[LogRecordProcessors](#logrecordprocessor) that are registered with the delegate -`LoggerProvider`. - ## EventLogger ### Emit Event From 56bf4c0ae9c17e00aad9d6020269c2a7b83ba1b8 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 12:36:45 -0700 Subject: [PATCH 03/14] removed non-normative language --- specification/logs/event-sdk.md | 2 +- specification/logs/sdk.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 0a6da15bba4..f0f46a46ef1 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -65,7 +65,7 @@ related to processing MUST be done by configuring the `LoggerProvider` directly. This method provides a way for provider to do any cleanup required. -`Shutdown` MUST be implemented at least by invoking `Shutdown` on the delegate +`Shutdown` MUST be implemented by invoking `Shutdown` on the delegate `LoggerProvider`, which in effect invokes `Shutdown` on all registered registered [LogRecordProcessors](#logrecordprocessor). diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 24ab9fbd106..113d2d3b3a7 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -138,7 +138,7 @@ implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the shutdown timeout configurable. -`Shutdown` MUST be implemented at least by invoking `Shutdown` on all +`Shutdown` MUST be implemented by invoking `Shutdown` on all registered [LogRecordProcessors](#logrecordprocessor). ### ForceFlush From 96364adb0dd1a67ad958473e1895a720335086e3 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 16:50:32 -0700 Subject: [PATCH 04/14] Update specification/logs/event-sdk.md Co-authored-by: Jamie Danielson --- specification/logs/event-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index f0f46a46ef1..15cc62ac6fa 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -42,7 +42,7 @@ All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SH ### EventLoggerProvider Creation -The SDK SHOULD allow the creation of multiple independent `EventLoggerProviders`s. +The SDK SHOULD allow the creation of multiple independent `EventLoggerProvider`s. ### EventLogger Creation From 5ae07d1181a80f39577f1c5fcf5e4ba7e08b6582 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 16:50:39 -0700 Subject: [PATCH 05/14] Update specification/logs/event-sdk.md Co-authored-by: Jamie Danielson --- specification/logs/event-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 15cc62ac6fa..511694fd742 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -46,7 +46,7 @@ The SDK SHOULD allow the creation of multiple independent `EventLoggerProvider`s ### EventLogger Creation -It SHOULD only be possible to create `EventLogger` instances through a `EventLoggerProvider` +It SHOULD only be possible to create `EventLogger` instances through an `EventLoggerProvider` (see [Events API](event-api.md)). The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). From c334d4548e39f218545e2acefaabd2ba60f64bc2 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 16:50:46 -0700 Subject: [PATCH 06/14] Update specification/logs/event-sdk.md Co-authored-by: Jamie Danielson --- specification/logs/event-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 511694fd742..ccb50346d19 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -67,7 +67,7 @@ This method provides a way for provider to do any cleanup required. `Shutdown` MUST be implemented by invoking `Shutdown` on the delegate `LoggerProvider`, which in effect invokes `Shutdown` on all registered -registered [LogRecordProcessors](#logrecordprocessor). +[LogRecordProcessors](#logrecordprocessor). ### ForceFlush From f009bf92e32ef4f8d140ebf9eb912299a31a753e Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 17:05:46 -0700 Subject: [PATCH 07/14] lint --- specification/logs/event-sdk.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index ccb50346d19..7f4cfcb5362 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -13,7 +13,6 @@ - [EventLoggerProvider](#eventloggerprovider) - [EventLogger](#eventlogger) * [Emit Event](#emit-event) -- [Additional Interfaces](#additional-interfaces) @@ -66,13 +65,13 @@ related to processing MUST be done by configuring the `LoggerProvider` directly. This method provides a way for provider to do any cleanup required. `Shutdown` MUST be implemented by invoking `Shutdown` on the delegate -`LoggerProvider`, which in effect invokes `Shutdown` on all registered -[LogRecordProcessors](#logrecordprocessor). +`LoggerProvider`, which in effect invokes `Shutdown` on all registered +[LogRecordProcessors](sdk.md#logrecordprocessor). ### ForceFlush This method provides a way for the provider to notify the delegate `LoggerProvider` -to force all registered [LogRecordProcessors](#logrecordprocessor) to immediately export all +to force all registered [LogRecordProcessors](sdk.md#logrecordprocessor) to immediately export all `LogRecords` that have not yet been exported. ## EventLogger From 1c55c6d313e32463e93b851a6ec175e633738cef Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 3 May 2024 17:14:26 -0700 Subject: [PATCH 08/14] updated toc --- specification/logs/event-sdk.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 7f4cfcb5362..553ff7307f4 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -11,6 +11,11 @@ - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) + * [EventLoggerProvider Creation](#eventloggerprovider-creation) + * [EventLogger Creation](#eventlogger-creation) + * [Configuration](#configuration) + * [Shutdown](#shutdown) + * [ForceFlush](#forceflush) - [EventLogger](#eventlogger) * [Emit Event](#emit-event) From 91d4c14b9f6a6038b9f4fd51e943d461f7ac4866 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Tue, 7 May 2024 15:49:17 -0700 Subject: [PATCH 09/14] update shutdown section --- specification/logs/event-sdk.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 553ff7307f4..7f078f084fc 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -69,9 +69,10 @@ related to processing MUST be done by configuring the `LoggerProvider` directly. This method provides a way for provider to do any cleanup required. -`Shutdown` MUST be implemented by invoking `Shutdown` on the delegate -`LoggerProvider`, which in effect invokes `Shutdown` on all registered -[LogRecordProcessors](sdk.md#logrecordprocessor). +`Shutdown` MUST NOT invoke `Shutdown` on the delegate +`LoggerProvider`, since the `LoggerProvider` could be used elsewhere. In order to +perform cleanup of the delegate `LoggerProvider`, its `Shutdown` method should be +called separately. ### ForceFlush From 01306cf015ebbf9ab6c4596a1061251e12e05909 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 10 May 2024 18:02:56 -0700 Subject: [PATCH 10/14] removed shutdown method --- specification/logs/event-sdk.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 7f078f084fc..2f11a07b3a7 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -65,15 +65,6 @@ message reporting that the specified value is invalid SHOULD be logged. The `EventLoggerProvider` MUST accept an instance of `LoggerProvider`. Any configuration related to processing MUST be done by configuring the `LoggerProvider` directly. -### Shutdown - -This method provides a way for provider to do any cleanup required. - -`Shutdown` MUST NOT invoke `Shutdown` on the delegate -`LoggerProvider`, since the `LoggerProvider` could be used elsewhere. In order to -perform cleanup of the delegate `LoggerProvider`, its `Shutdown` method should be -called separately. - ### ForceFlush This method provides a way for the provider to notify the delegate `LoggerProvider` From 0dae12e0ce2006728ef74f546ebf25d5831a29e4 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 10 May 2024 18:06:14 -0700 Subject: [PATCH 11/14] Update specification/logs/event-sdk.md Co-authored-by: Trask Stalnaker --- specification/logs/event-sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 2f11a07b3a7..ab063e5fd01 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -73,6 +73,8 @@ to force all registered [LogRecordProcessors](sdk.md#logrecordprocessor) to imme ## EventLogger +The `EventLogger` MUST be implemented as a proxy to an instance of [`Logger`](./sdk.md#logger). + ### Emit Event Emit a `LogRecord` representing an `Event`. From 0638b21fc64f2edae93d8e38c9beea9d5eb4d492 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 10 May 2024 18:06:34 -0700 Subject: [PATCH 12/14] Update specification/logs/event-sdk.md Co-authored-by: Trask Stalnaker --- specification/logs/event-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index ab063e5fd01..cc822987b0d 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -40,7 +40,7 @@ The SDK MUST use the [Logs SDK](./sdk.md) to generate, process and export `LogRe ## EventLoggerProvider -The `EventLoggerProvider` MUST be implemented as a proxy to an instance of `LoggerProvider`. +The `EventLoggerProvider` MUST be implemented as a proxy to an instance of [`LoggerProvider`](./sdk.md#loggerprovider). All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SHOULD be associated with the `Resource` from the provided `LoggerProvider`. From 43df5e1ebab6927b65057fb30e2641f7b8403ccd Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Fri, 10 May 2024 18:24:27 -0700 Subject: [PATCH 13/14] updated links --- specification/logs/event-sdk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index cc822987b0d..1ebb3ba3dd3 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -14,7 +14,6 @@ * [EventLoggerProvider Creation](#eventloggerprovider-creation) * [EventLogger Creation](#eventlogger-creation) * [Configuration](#configuration) - * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [EventLogger](#eventlogger) * [Emit Event](#emit-event) From 55db7ab4c0ec1b383f50d1214593b86bd473bd64 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Tue, 14 May 2024 06:15:15 -0700 Subject: [PATCH 14/14] updated changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 13e5b73e50b..e8cee03c5c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ release. ### Events +- Add specification for EventLogger and EventLoggerProvider + ([#4031](https://github.com/open-telemetry/opentelemetry-specification/pull/4031)) + ### Resource ### OpenTelemetry Protocol