[Logs] Add optional Ergonomic API

.gitignore

@@ -29,6 +29,9 @@ internal/tools/bin
 node_modules/
 package-lock.json
 
+# Python virtual environment
+venv/
+
 # Visual Studio Code
 .vscode
 

CHANGELOG.md

@@ -15,6 +15,9 @@ release.
 
 ### Logs
 
+- Add optional Ergonomic API.
+  ([#4741](https://github.com/open-telemetry/opentelemetry-specification/pull/4741))
+
 ### Baggage
 
 ### Profiles

spec-compliance-matrix.md

@@ -201,6 +201,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 | Logger.Emit(LogRecord) |  | + | + | + | + | + |  | + |  | + | - |  |
 | LogRecord.Set EventName |  | + |  |  |  |  |  |  | + | + |  |  |
 | Logger.Enabled | X | + |  |  |  |  |  | + | + | + |  |  |
+| Ergonomic API | X |  |  |  |  |  |  |  |  |  |  |  |
 | SimpleLogRecordProcessor |  | + | + | + | + | + |  | + |  | + |  |  |
 | BatchLogRecordProcessor |  | + | + | + | + | + |  | + |  | + |  |  |
 | Can plug custom LogRecordProcessor |  | + | + | + | + | + |  | + |  | + |  |  |

spec-compliance-matrix/template.yaml

@@ -237,6 +237,8 @@ sections:
       - name: LogRecord.Set EventName
       - name: Logger.Enabled
         optional: true
+      - name: Ergonomic API
+        optional: true
       - name: SimpleLogRecordProcessor
       - name: BatchLogRecordProcessor
       - name: Can plug custom LogRecordProcessor

specification/logs/api.md

@@ -6,7 +6,7 @@ aliases: [bridge-api]
 
 # Logs API
 
-**Status**: [Stable](../document-status.md)
+**Status**: [Stable](../document-status.md), except where otherwise specified
 
 <details>
 <summary>Table of Contents</summary>
@@ -23,6 +23,7 @@ aliases: [bridge-api]
   * [Enabled](#enabled)
 - [Optional and required parameters](#optional-and-required-parameters)
 - [Concurrency requirements](#concurrency-requirements)
+- [Ergonomic API](#ergonomic-api)
 - [References](#references)
 
 <!-- tocstop -->
@@ -35,7 +36,8 @@ which use this API to bridge between existing logging libraries and the
 OpenTelemetry log data model.
 
 The Logs API can also be directly called by instrumentation libraries
-as well as instrumented libraries or applications.
+as well as instrumented libraries or applications. However, languages are also
+free to provide a more [ergonomic API](#ergonomic-api) for direct usage.
 
 The Logs API consist of these main components:
 
@@ -167,6 +169,20 @@ specific guarantees and safeties.
 
 **Logger** - all methods are safe to be called concurrently.
 
+## Ergonomic API
+
+**Status**: [Development](../document-status.md)
+
+Languages MAY additionally provide a more ergonomic and convenient logging API
+that it is better suited for direct usage by instrumentation libraries,
+instrumented libraries, and applications.
+
+The ergonomic API SHOULD make it easier to emit logs and events following the
+[log semantics](https://opentelemetry.io/docs/specs/semconv/general/logs/)
+and the [event semantics](https://opentelemetry.io/docs/specs/semconv/general/events/).
+
+The design of the ergonomic API SHOULD be idiomatic for its language.
+
 ## References
 
 - [OTEP0150 Logging Library SDK Prototype Specification](../../oteps/logs/0150-logging-library-sdk.md)