From 137911d1add643928776dcdcfbd307831a40845b Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Mon, 30 Sep 2024 18:20:16 -0700 Subject: [PATCH 01/30] Introduce the new user-facing Logs API as a placeholder --- .gitignore | 5 +++- CHANGELOG.md | 3 +++ specification/README.md | 1 + specification/logs/bridge-api.md | 9 +++++++ specification/logs/event-api.md | 9 +++++++ specification/logs/event-sdk.md | 9 +++++++ specification/logs/public-api.md | 40 ++++++++++++++++++++++++++++++++ specification/logs/sdk.md | 9 +++++++ 8 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 specification/logs/public-api.md diff --git a/.gitignore b/.gitignore index c9508b6a86a..7aadede2c9e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,4 +30,7 @@ node_modules/ package-lock.json # Visual Studio Code -.vscode \ No newline at end of file +.vscode + +# Visual Studio +.vs \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index df9d5bca1e6..d765f2e7732 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,9 @@ release. ([#4221](https://github.com/open-telemetry/opentelemetry-specification/pull/4221)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- Introduce initial placeholder for the new user-facing Logs API, adding references + to existing API's informing of the coming changes while the definition is defined. + ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) ### Events diff --git a/specification/README.md b/specification/README.md index d1136d70243..a4bce3cfb56 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,6 +29,7 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) + - [Public API](logs/public-api.md) - [Bridge API](logs/bridge-api.md) - [Event API](logs/event-api.md) - SDK Specification diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 258966c0839..7d24ca8ab4d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -44,6 +45,14 @@ graph TD B -->|Emit| C(LogRecord) ``` +## Public API Development + +We are currently in the process of defining a new [user-facing Logs API](./public-api.md). Unlike this Logs Bridge API, the new API is intended to be called by both application developers and logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Logs Bridge API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Log Bridge API at this time. + ## LoggerProvider `Logger`s can be accessed with a `LoggerProvider`. diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea5c58116fe..ea556a6c589 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -30,6 +31,14 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. +## Public API Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Event API definition at this time. + ## Event Data model Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 1a9bc0ee829..b1327548509 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,6 +9,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -29,6 +30,14 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Event SDK at this time. + ## Overview From OpenTelemetry's perspective LogRecords and Events are both represented diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md new file mode 100644 index 00000000000..56df03b2a77 --- /dev/null +++ b/specification/logs/public-api.md @@ -0,0 +1,40 @@ +# Public Logs API + +**Status**: [Development](../document-status.md), except where otherwise specified + +
+Table of Contents + + + + + +- [Logger](#logger) + * [Logger operations](#logger-operations) +- [References](#references) + + + +
+ +Note: this document is a work in progress as we move towards defining a user-facing Logs API. Unlike the current [Logs Bridge API](./bridge-api.md), this new API is intended to be called by both application developers and logging +library authors to build +[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), +which use this API to bridge between existing logging libraries and the +OpenTelemetry log data model. + +## Logger + +The `Logger` is responsible for emitting `LogRecord`s. + +### Logger operations + +The full set of operations that a `Logger` will provide is not yet defined. The +intent is that is will provide the capabalities needed to emit a `LogRecord` as is currently provided by + +* [Logs Bridge API](./bridge-api.md) +* [Events API](./event-api.md) + +## References + +- [OTEP0265 Event Basics](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md#api) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5d29e2b6984..896972e7052 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,6 +7,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -46,6 +47,14 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API/SDK will incorporate the current functionality of this existing API/SDK and once it is defined and implemented, this SDK usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Logging SDK definition at this time. + ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) From 7c78efff144eaf1620880994ec842c4f1f830f3a Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:00:48 -0700 Subject: [PATCH 02/30] Rename Public API to Instrumentation API and move into the bridge api --- specification/README.md | 1 - specification/logs/bridge-api.md | 20 +++++++++------- specification/logs/event-api.md | 8 ++++--- specification/logs/event-sdk.md | 6 ++--- specification/logs/public-api.md | 40 -------------------------------- specification/logs/sdk.md | 14 ++++------- 6 files changed, 24 insertions(+), 65 deletions(-) delete mode 100644 specification/logs/public-api.md diff --git a/specification/README.md b/specification/README.md index a4bce3cfb56..d1136d70243 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,7 +29,6 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) - - [Public API](logs/public-api.md) - [Bridge API](logs/bridge-api.md) - [Event API](logs/event-api.md) - SDK Specification diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7d24ca8ab4d..f66988fcb3b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,7 +9,6 @@ -- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -17,6 +16,7 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) +- [Instrumentation API](#instrumentation-api) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -45,14 +45,6 @@ graph TD B -->|Emit| C(LogRecord) ``` -## Public API Development - -We are currently in the process of defining a new [user-facing Logs API](./public-api.md). Unlike this Logs Bridge API, the new API is intended to be called by both application developers and logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. - -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Logs Bridge API usage will be migrated, deprecated, renamed and eventually removed. - -No further work is scheduled for the current Log Bridge API at this time. - ## LoggerProvider `Logger`s can be accessed with a `LoggerProvider`. @@ -154,6 +146,16 @@ 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. +## Instrumentation API + +**Status**: [Development](../document-status.md) + +This set of API functions will provide the capabalities needed to emit a +`LogRecord` as is currently provided by + +* [Logs Bridge API](./bridge-api.md) +* [Events API](./event-api.md) + ## Optional and required parameters The operations defined include various parameters, some of which are marked diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea556a6c589..61c77140377 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,7 +9,7 @@ -- [Public API Development](#public-api-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -31,9 +31,11 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Public API Development +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +**Status**: [Development](../document-status.md) + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index b1327548509..3fce8b0c4b4 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,7 +9,7 @@ -- [Public API/SDK Development](#public-apisdk-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -30,9 +30,9 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. -## Public API/SDK Development +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md deleted file mode 100644 index 56df03b2a77..00000000000 --- a/specification/logs/public-api.md +++ /dev/null @@ -1,40 +0,0 @@ -# Public Logs API - -**Status**: [Development](../document-status.md), except where otherwise specified - -
-Table of Contents - - - - - -- [Logger](#logger) - * [Logger operations](#logger-operations) -- [References](#references) - - - -
- -Note: this document is a work in progress as we move towards defining a user-facing Logs API. Unlike the current [Logs Bridge API](./bridge-api.md), this new API is intended to be called by both application developers and logging -library authors to build -[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), -which use this API to bridge between existing logging libraries and the -OpenTelemetry log data model. - -## Logger - -The `Logger` is responsible for emitting `LogRecord`s. - -### Logger operations - -The full set of operations that a `Logger` will provide is not yet defined. The -intent is that is will provide the capabalities needed to emit a `LogRecord` as is currently provided by - -* [Logs Bridge API](./bridge-api.md) -* [Events API](./event-api.md) - -## References - -- [OTEP0265 Event Basics](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md#api) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 896972e7052..a4ef413ab0a 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,7 +7,6 @@ -- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -35,6 +34,7 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) +- [Instrumentation API](#instrumentation-api) @@ -47,14 +47,6 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. -## Public API/SDK Development - -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). - -The intent is that this new API/SDK will incorporate the current functionality of this existing API/SDK and once it is defined and implemented, this SDK usage will be migrated, deprecated, renamed and eventually removed. - -No further work is scheduled for the current Logging SDK definition at this time. - ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) @@ -547,4 +539,8 @@ 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. +## Instrumentation API + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). + - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From 8b1ce31108200c1c084d3ebe49eb3d1436c3fbc8 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:25:36 -0700 Subject: [PATCH 03/30] Address naming issues --- specification/logs/event-api.md | 4 +--- specification/logs/event-sdk.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 61c77140377..e52aebaf566 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,11 +33,9 @@ The Event API consists of these main components: ## Instrumentation API Development -**Status**: [Development](../document-status.md) - Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event API definition at this time. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 3fce8b0c4b4..51f9f0f433b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -34,7 +34,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that Logs SDK will incorporate the current functionality of this existing SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event SDK at this time. From af1ea8c32d326635fccd0a29256edeb443718b5b Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:37:12 -0700 Subject: [PATCH 04/30] Update specification/logs/event-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index e52aebaf566..33d59989dd9 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -35,7 +35,7 @@ The Event API consists of these main components: Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event API definition at this time. From f8d6d6c1c259e2cf4157375a599056e7ae8cfd4b Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:37:52 -0700 Subject: [PATCH 05/30] Update specification/logs/bridge-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/bridge-api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index f66988fcb3b..65cc8046bba 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -153,7 +153,6 @@ up-to-date response. This set of API functions will provide the capabalities needed to emit a `LogRecord` as is currently provided by -* [Logs Bridge API](./bridge-api.md) * [Events API](./event-api.md) ## Optional and required parameters From 90b4b8f48c5bec2f1c0accadfc88d92be3b5299e Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:38:05 -0700 Subject: [PATCH 06/30] Update specification/logs/event-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 33d59989dd9..fd841946fb2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -37,7 +37,7 @@ Note!: We are currently in the process of defining a new [Instrumentation API](. The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. -No further work is scheduled for the current Event API definition at this time. +No further work is scheduled for the current Events API definition at this time. ## Event Data model From e72b8419d108934ab12518f336f5216c6cdbce0a Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:51:44 -0700 Subject: [PATCH 07/30] Update specification/logs/bridge-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/bridge-api.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 65cc8046bba..4c951b250c5 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -151,9 +151,7 @@ up-to-date response. **Status**: [Development](../document-status.md) This set of API functions will provide the capabalities needed to emit a -`LogRecord` as is currently provided by - -* [Events API](./event-api.md) +`LogRecord` as is currently provided by [Events API](./event-api.md). ## Optional and required parameters From c6ead01f8c101c7e1398e7732085afc8166cc265 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:22 -0700 Subject: [PATCH 08/30] Update specification/logs/bridge-api.md Co-authored-by: Trask Stalnaker --- specification/logs/bridge-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 4c951b250c5..97b8058477d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -150,7 +150,7 @@ up-to-date response. **Status**: [Development](../document-status.md) -This set of API functions will provide the capabalities needed to emit a +This set of API functions will provide the capabilities needed to emit a `LogRecord` as is currently provided by [Events API](./event-api.md). ## Optional and required parameters From 971bc4b7a5e3449e1616b5b3d9cd4e6dd9c44de3 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:31 -0700 Subject: [PATCH 09/30] Update specification/logs/event-api.md Co-authored-by: Trask Stalnaker --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index fd841946fb2..bd6efc0c1a5 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,7 +33,7 @@ The Event API consists of these main components: ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. From 476e57ee83ffced6e2de98e68fdeb9923f49f0d5 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:48 -0700 Subject: [PATCH 10/30] Update specification/logs/event-api.md Co-authored-by: Trask Stalnaker --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index bd6efc0c1a5..fd717d60e22 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -35,7 +35,7 @@ The Event API consists of these main components: Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Logs Instrumentation API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Events API definition at this time. From 82546628d1fba2b217e7157d44a62eabad6df088 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:00 -0700 Subject: [PATCH 11/30] 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 51f9f0f433b..932cfd9e010 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -34,7 +34,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that Logs SDK will incorporate the current functionality of this existing SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. +The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event SDK at this time. From b26f162f377b1076ee98e0ff3fac18d6bcb7eeb0 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:10 -0700 Subject: [PATCH 12/30] Update specification/logs/sdk.md Co-authored-by: Trask Stalnaker --- specification/logs/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index a4ef413ab0a..cdc97ae6220 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -541,6 +541,6 @@ authors MAY decide if they want to make the shutdown timeout configurable. ## Instrumentation API -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From 6c8a343e3b1ce9b0adebd5a1344647585de54431 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:52 -0700 Subject: [PATCH 13/30] 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 932cfd9e010..347ca42c71b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -32,7 +32,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. From 92b54e0ee2f09890540efb4659312b0041014959 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Wed, 2 Oct 2024 17:42:08 -0700 Subject: [PATCH 14/30] Update specification/logs/event-api.md Co-authored-by: Liudmila Molkova --- specification/logs/event-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index fd717d60e22..23c6b013c73 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,7 +33,8 @@ The Event API consists of these main components: ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this Logs Instrumentation API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. From 4148f847c8f6f06f93d7403b9e71605e05113c50 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Wed, 2 Oct 2024 17:42:22 -0700 Subject: [PATCH 15/30] Update specification/logs/sdk.md Co-authored-by: Liudmila Molkova --- specification/logs/sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index cdc97ae6220..01456a158a4 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -541,6 +541,7 @@ authors MAY decide if they want to make the shutdown timeout configurable. ## Instrumentation API -Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From fde365b7e68ad18770927eed785d8b8e047bc316 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Wed, 2 Oct 2024 17:42:34 -0700 Subject: [PATCH 16/30] Update specification/logs/event-sdk.md Co-authored-by: Liudmila Molkova --- specification/logs/event-sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 347ca42c71b..21606ce2827 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -32,7 +32,8 @@ All implementations of the OpenTelemetry API MUST provide an SDK. ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. From 09c53770709f9cbfb3e247689ad3d709d8abf797 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Mon, 30 Sep 2024 18:20:16 -0700 Subject: [PATCH 17/30] Introduce the new user-facing Logs API as a placeholder --- .gitignore | 5 +++- CHANGELOG.md | 3 +++ specification/README.md | 1 + specification/logs/bridge-api.md | 9 +++++++ specification/logs/event-api.md | 9 +++++++ specification/logs/event-sdk.md | 9 +++++++ specification/logs/public-api.md | 40 ++++++++++++++++++++++++++++++++ specification/logs/sdk.md | 9 +++++++ 8 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 specification/logs/public-api.md diff --git a/.gitignore b/.gitignore index c9508b6a86a..7aadede2c9e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,4 +30,7 @@ node_modules/ package-lock.json # Visual Studio Code -.vscode \ No newline at end of file +.vscode + +# Visual Studio +.vs \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index df9d5bca1e6..d765f2e7732 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,9 @@ release. ([#4221](https://github.com/open-telemetry/opentelemetry-specification/pull/4221)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- Introduce initial placeholder for the new user-facing Logs API, adding references + to existing API's informing of the coming changes while the definition is defined. + ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) ### Events diff --git a/specification/README.md b/specification/README.md index d1136d70243..a4bce3cfb56 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,6 +29,7 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) + - [Public API](logs/public-api.md) - [Bridge API](logs/bridge-api.md) - [Event API](logs/event-api.md) - SDK Specification diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 258966c0839..7d24ca8ab4d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -44,6 +45,14 @@ graph TD B -->|Emit| C(LogRecord) ``` +## Public API Development + +We are currently in the process of defining a new [user-facing Logs API](./public-api.md). Unlike this Logs Bridge API, the new API is intended to be called by both application developers and logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Logs Bridge API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Log Bridge API at this time. + ## LoggerProvider `Logger`s can be accessed with a `LoggerProvider`. diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea5c58116fe..ea556a6c589 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -30,6 +31,14 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. +## Public API Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Event API definition at this time. + ## Event Data model Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 1a9bc0ee829..b1327548509 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,6 +9,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -29,6 +30,14 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Event SDK at this time. + ## Overview From OpenTelemetry's perspective LogRecords and Events are both represented diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md new file mode 100644 index 00000000000..56df03b2a77 --- /dev/null +++ b/specification/logs/public-api.md @@ -0,0 +1,40 @@ +# Public Logs API + +**Status**: [Development](../document-status.md), except where otherwise specified + +
+Table of Contents + + + + + +- [Logger](#logger) + * [Logger operations](#logger-operations) +- [References](#references) + + + +
+ +Note: this document is a work in progress as we move towards defining a user-facing Logs API. Unlike the current [Logs Bridge API](./bridge-api.md), this new API is intended to be called by both application developers and logging +library authors to build +[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), +which use this API to bridge between existing logging libraries and the +OpenTelemetry log data model. + +## Logger + +The `Logger` is responsible for emitting `LogRecord`s. + +### Logger operations + +The full set of operations that a `Logger` will provide is not yet defined. The +intent is that is will provide the capabalities needed to emit a `LogRecord` as is currently provided by + +* [Logs Bridge API](./bridge-api.md) +* [Events API](./event-api.md) + +## References + +- [OTEP0265 Event Basics](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md#api) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5d29e2b6984..896972e7052 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,6 +7,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -46,6 +47,14 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API/SDK will incorporate the current functionality of this existing API/SDK and once it is defined and implemented, this SDK usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Logging SDK definition at this time. + ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) From 5ba0a22f470f4d7bed75d83dbe29507cb6b81496 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:00:48 -0700 Subject: [PATCH 18/30] Rename Public API to Instrumentation API and move into the bridge api --- specification/README.md | 1 - specification/logs/bridge-api.md | 20 +++++++++------- specification/logs/event-api.md | 8 ++++--- specification/logs/event-sdk.md | 6 ++--- specification/logs/public-api.md | 40 -------------------------------- specification/logs/sdk.md | 14 ++++------- 6 files changed, 24 insertions(+), 65 deletions(-) delete mode 100644 specification/logs/public-api.md diff --git a/specification/README.md b/specification/README.md index a4bce3cfb56..d1136d70243 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,7 +29,6 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) - - [Public API](logs/public-api.md) - [Bridge API](logs/bridge-api.md) - [Event API](logs/event-api.md) - SDK Specification diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 7d24ca8ab4d..f66988fcb3b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,7 +9,6 @@ -- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -17,6 +16,7 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) +- [Instrumentation API](#instrumentation-api) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -45,14 +45,6 @@ graph TD B -->|Emit| C(LogRecord) ``` -## Public API Development - -We are currently in the process of defining a new [user-facing Logs API](./public-api.md). Unlike this Logs Bridge API, the new API is intended to be called by both application developers and logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. - -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Logs Bridge API usage will be migrated, deprecated, renamed and eventually removed. - -No further work is scheduled for the current Log Bridge API at this time. - ## LoggerProvider `Logger`s can be accessed with a `LoggerProvider`. @@ -154,6 +146,16 @@ 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. +## Instrumentation API + +**Status**: [Development](../document-status.md) + +This set of API functions will provide the capabalities needed to emit a +`LogRecord` as is currently provided by + +* [Logs Bridge API](./bridge-api.md) +* [Events API](./event-api.md) + ## Optional and required parameters The operations defined include various parameters, some of which are marked diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea556a6c589..61c77140377 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,7 +9,7 @@ -- [Public API Development](#public-api-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -31,9 +31,11 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Public API Development +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +**Status**: [Development](../document-status.md) + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index b1327548509..3fce8b0c4b4 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,7 +9,7 @@ -- [Public API/SDK Development](#public-apisdk-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -30,9 +30,9 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. -## Public API/SDK Development +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md deleted file mode 100644 index 56df03b2a77..00000000000 --- a/specification/logs/public-api.md +++ /dev/null @@ -1,40 +0,0 @@ -# Public Logs API - -**Status**: [Development](../document-status.md), except where otherwise specified - -
-Table of Contents - - - - - -- [Logger](#logger) - * [Logger operations](#logger-operations) -- [References](#references) - - - -
- -Note: this document is a work in progress as we move towards defining a user-facing Logs API. Unlike the current [Logs Bridge API](./bridge-api.md), this new API is intended to be called by both application developers and logging -library authors to build -[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), -which use this API to bridge between existing logging libraries and the -OpenTelemetry log data model. - -## Logger - -The `Logger` is responsible for emitting `LogRecord`s. - -### Logger operations - -The full set of operations that a `Logger` will provide is not yet defined. The -intent is that is will provide the capabalities needed to emit a `LogRecord` as is currently provided by - -* [Logs Bridge API](./bridge-api.md) -* [Events API](./event-api.md) - -## References - -- [OTEP0265 Event Basics](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md#api) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 896972e7052..a4ef413ab0a 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,7 +7,6 @@ -- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -35,6 +34,7 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) +- [Instrumentation API](#instrumentation-api) @@ -47,14 +47,6 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. -## Public API/SDK Development - -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). - -The intent is that this new API/SDK will incorporate the current functionality of this existing API/SDK and once it is defined and implemented, this SDK usage will be migrated, deprecated, renamed and eventually removed. - -No further work is scheduled for the current Logging SDK definition at this time. - ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) @@ -547,4 +539,8 @@ 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. +## Instrumentation API + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). + - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From 49952f7ddee79bf4522253d1feaab0ea864e465e Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:25:36 -0700 Subject: [PATCH 19/30] Address naming issues --- specification/logs/event-api.md | 4 +--- specification/logs/event-sdk.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 61c77140377..e52aebaf566 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,11 +33,9 @@ The Event API consists of these main components: ## Instrumentation API Development -**Status**: [Development](../document-status.md) - Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event API definition at this time. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 3fce8b0c4b4..51f9f0f433b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -34,7 +34,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that Logs SDK will incorporate the current functionality of this existing SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event SDK at this time. From 34e28a88b5427582ca0c72b6f4ed1865dd793207 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:37:12 -0700 Subject: [PATCH 20/30] Update specification/logs/event-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index e52aebaf566..33d59989dd9 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -35,7 +35,7 @@ The Event API consists of these main components: Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event API definition at this time. From b6197b262dca83136741afe0e8cb0330bbbdf07b Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:37:52 -0700 Subject: [PATCH 21/30] Update specification/logs/bridge-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/bridge-api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index f66988fcb3b..65cc8046bba 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -153,7 +153,6 @@ up-to-date response. This set of API functions will provide the capabalities needed to emit a `LogRecord` as is currently provided by -* [Logs Bridge API](./bridge-api.md) * [Events API](./event-api.md) ## Optional and required parameters From 7118cd6bd8aef349f1e80248efc17b2158ffe2ca Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:38:05 -0700 Subject: [PATCH 22/30] Update specification/logs/event-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 33d59989dd9..fd841946fb2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -37,7 +37,7 @@ Note!: We are currently in the process of defining a new [Instrumentation API](. The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. -No further work is scheduled for the current Event API definition at this time. +No further work is scheduled for the current Events API definition at this time. ## Event Data model From 93a4954265daa8757d01396b462b25c7b595210b Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:51:44 -0700 Subject: [PATCH 23/30] Update specification/logs/bridge-api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- specification/logs/bridge-api.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 65cc8046bba..4c951b250c5 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -151,9 +151,7 @@ up-to-date response. **Status**: [Development](../document-status.md) This set of API functions will provide the capabalities needed to emit a -`LogRecord` as is currently provided by - -* [Events API](./event-api.md) +`LogRecord` as is currently provided by [Events API](./event-api.md). ## Optional and required parameters From 318dc2bbe9b01290f327a9d1da5c95759c188e93 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:22 -0700 Subject: [PATCH 24/30] Update specification/logs/bridge-api.md Co-authored-by: Trask Stalnaker --- specification/logs/bridge-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 4c951b250c5..97b8058477d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -150,7 +150,7 @@ up-to-date response. **Status**: [Development](../document-status.md) -This set of API functions will provide the capabalities needed to emit a +This set of API functions will provide the capabilities needed to emit a `LogRecord` as is currently provided by [Events API](./event-api.md). ## Optional and required parameters From 19e6bf1989e9dc0c9e2a45a6fb11f7708c59cae2 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:31 -0700 Subject: [PATCH 25/30] Update specification/logs/event-api.md Co-authored-by: Trask Stalnaker --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index fd841946fb2..bd6efc0c1a5 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,7 +33,7 @@ The Event API consists of these main components: ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. From 54aaf5f6d2811cafd9cc3b6b0ab1da6c1f8670a9 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:06:48 -0700 Subject: [PATCH 26/30] Update specification/logs/event-api.md Co-authored-by: Trask Stalnaker --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index bd6efc0c1a5..fd717d60e22 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -35,7 +35,7 @@ The Event API consists of these main components: Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that this Instrumentation API will incorporate the current functionality of this existing API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. +The intent is that this Logs Instrumentation API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Events API definition at this time. From d5844b5ecabdd47bbe906828ef5dea2db13a7a10 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:00 -0700 Subject: [PATCH 27/30] 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 51f9f0f433b..932cfd9e010 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -34,7 +34,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). -The intent is that Logs SDK will incorporate the current functionality of this existing SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. +The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. No further work is scheduled for the current Event SDK at this time. From c21d36fe7727691fbe6354bd75c0626f1803c2b7 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:10 -0700 Subject: [PATCH 28/30] Update specification/logs/sdk.md Co-authored-by: Trask Stalnaker --- specification/logs/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index a4ef413ab0a..cdc97ae6220 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -541,6 +541,6 @@ authors MAY decide if they want to make the shutdown timeout configurable. ## Instrumentation API -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From 64a129200bedd8417364f4645526271cf09dd756 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 14:07:52 -0700 Subject: [PATCH 29/30] 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 932cfd9e010..347ca42c71b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -32,7 +32,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. ## Instrumentation API Development -Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). +Note!: We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. From 551bae9ff58a124d081d1bc40706a6aa6d3b33f0 Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Mon, 7 Oct 2024 09:27:16 -0700 Subject: [PATCH 30/30] Update all references to "Logs Instrumentation API" --- specification/logs/bridge-api.md | 4 ++-- specification/logs/event-api.md | 6 +++--- specification/logs/event-sdk.md | 6 +++--- specification/logs/sdk.md | 6 +++--- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 97b8058477d..7b8c2b07e92 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -16,7 +16,7 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) -- [Instrumentation API](#instrumentation-api) +- [Logs Instrumentation API](#logs-instrumentation-api) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -146,7 +146,7 @@ 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. -## Instrumentation API +## Logs Instrumentation API **Status**: [Development](../document-status.md) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 23c6b013c73..b239ba31cea 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,7 +9,7 @@ -- [Instrumentation API Development](#instrumentation-api-development) +- [Logs Instrumentation API Development](#logs-instrumentation-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -31,10 +31,10 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Instrumentation API Development +## Logs Instrumentation API Development > [!NOTE] -> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). The intent is that this Logs Instrumentation API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 21606ce2827..b76632af67d 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,7 +9,7 @@ -- [Instrumentation API Development](#instrumentation-api-development) +- [Logs Instrumentation API Development](#logs-instrumentation-api-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -30,10 +30,10 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. -## Instrumentation API Development +## Logs Instrumentation API Development > [!NOTE] -> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 01456a158a4..5212fa29a77 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -34,7 +34,7 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) -- [Instrumentation API](#instrumentation-api) +- [Logs Instrumentation API](#logs-instrumentation-api) @@ -539,9 +539,9 @@ 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. -## Instrumentation API +## Logs Instrumentation API > [!NOTE] -> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#instrumentation-api). +> 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)