Introduce the new user-facing Logs API as a placeholder

.gitignore

@@ -30,4 +30,7 @@ node_modules/
 package-lock.json
 
 # Visual Studio Code
-.vscode
+.vscode
+
+# Visual Studio
+.vs

CHANGELOG.md

@@ -33,6 +33,9 @@ release.
   ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203))
 - 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
 

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

specification/logs/bridge-api.md

@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [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`.

specification/logs/event-api.md

@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [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):

specification/logs/event-sdk.md

@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [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

specification/logs/public-api.md

@@ -0,0 +1,40 @@
+# Public Logs API
+
+**Status**: [Development](../document-status.md), except where otherwise specified
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Logger](#logger)
+  * [Logger operations](#logger-operations)
+- [References](#references)
+
+<!-- tocstop -->
+
+</details>
+
+<b>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.</b>
+
+## 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)

specification/logs/sdk.md

@@ -46,6 +46,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)