Introduce the new user-facing Logs API as a placeholder (#4236)

Part of open-telemetry/oteps#265 --------- Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]>
open-telemetry · Oct 9, 2024 · b9d347a · b9d347a
1 parent 630896f
commit b9d347a
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -30,4 +30,7 @@ node_modules/
 package-lock.json
 
 # Visual Studio Code
-.vscode
+.vscode
+
+# Visual Studio
+.vs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,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/logs/bridge-api.md b/specification/logs/bridge-api.md
@@ -16,6 +16,7 @@
   * [Logger operations](#logger-operations)
     + [Emit a LogRecord](#emit-a-logrecord)
     + [Enabled](#enabled)
+- [Logs Instrumentation API](#logs-instrumentation-api)
 - [Optional and required parameters](#optional-and-required-parameters)
 - [Concurrency requirements](#concurrency-requirements)
 - [Artifact Naming](#artifact-naming)
@@ -145,6 +146,13 @@ SHOULD be documented that instrumentation authors needs to call this API each
 time they [emit a LogRecord](#emit-a-logrecord) to ensure they have the most
 up-to-date response.
 
+## Logs Instrumentation API
+
+**Status**: [Development](../document-status.md)
+
+This set of API functions will provide the capabilities needed to emit a
+`LogRecord` as is currently provided by [Events API](./event-api.md).
+
 ## 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
@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [Logs Instrumentation API Development](#logs-instrumentation-api-development)
 - [Event Data model](#event-data-model)
 - [Event API use cases](#event-api-use-cases)
 - [EventLoggerProvider](#eventloggerprovider)
@@ -30,6 +31,15 @@ The Event API consists of these main components:
   provides access to `EventLogger`s.
 * [EventLogger](#eventlogger) is the component responsible for emitting events.
 
+## Logs Instrumentation API Development
+
+> [!NOTE]
+> 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.
+
+No further work is scheduled for the current Events 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
@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [Logs Instrumentation API Development](#logs-instrumentation-api-development)
 - [Overview](#overview)
 - [EventLoggerProvider](#eventloggerprovider)
   * [EventLoggerProvider Creation](#eventloggerprovider-creation)
@@ -29,6 +30,15 @@ API that provides users with this functionally.
 
 All implementations of the OpenTelemetry API MUST provide an SDK.
 
+## Logs Instrumentation API Development
+
+> [!NOTE]
+> 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.
+
+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/sdk.md b/specification/logs/sdk.md
@@ -34,6 +34,7 @@
     + [Export](#export)
     + [ForceFlush](#forceflush-2)
     + [Shutdown](#shutdown-1)
+- [Logs Instrumentation API](#logs-instrumentation-api)
 
 <!-- tocstop -->
 
@@ -538,4 +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.
 
+## Logs Instrumentation API
+
+> [!NOTE]
+> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api).
+
 - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)