[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

@@ -17,6 +17,8 @@ release.
 
 - Stabilize `LogRecordProcessor.Enabled`.
   ([#4717](https://github.com/open-telemetry/opentelemetry-specification/pull/4717))
+- Add optional Ergonomic API.
+  ([#4741](https://github.com/open-telemetry/opentelemetry-specification/pull/4741))
 
 ### Baggage
 

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/README.md

@@ -143,15 +143,22 @@ Given the above state of the logging space we took the following approach:
   OpenTelemetry log data model. OpenTelemetry Collector can read such logs and
   translate them to OpenTelemetry log data model.
 
-- OpenTelemetry defines a Logs API
-  for [emitting LogRecords](./api.md#emit-a-logrecord). It is provided for
-  library authors to build [log appender](../glossary.md#log-appender--bridge),
+- OpenTelemetry defines a [Logs API](./api.md)
+  for [emitting LogRecords](./api.md#emit-a-logrecord). It is primarily provided
+  for library authors to build [log appenders](../glossary.md#log-appender--bridge),
   which use the API to bridge between existing logging libraries and the
-  OpenTelemetry log data model. Existing logging libraries generally provide
-  a much richer set of features than what is defined in OpenTelemetry.
-  It is NOT a goal of OpenTelemetry to ship a feature-rich logging library.
-  Yet, the Logs API can also be used directly if one prefers to couple the code
-  to it instead of using a bridged logging library.
+  OpenTelemetry log data model. The Logs API can also be used directly by
+  applications, which is particularly important for:
+
+  - **Instrumentation libraries** to avoid coupling to a particular logging library.
+  - **Emitting structured logs and events** following [semantic conventions](https://opentelemetry.io/docs/specs/semconv/),
+  - **Scenarios requiring direct control** over log emission without
+    intermediary logging frameworks.
+
+  Note that existing logging libraries generally provide a much richer set of
+  features than what is defined in OpenTelemetry. Yet, languages may provide
+  an [ergonomic API](./api.md#ergonomic-api) for better developer experience
+  when using it directly.
 
 - OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md),
   which enables configuration of [processing](./sdk.md#logrecordprocessor)
@@ -375,17 +382,30 @@ application startup.
 
 These are greenfield developments. OpenTelemetry provides recommendations and
 best practices about how to emit logs (along with traces and metrics) from these
-applications. For applicable languages and frameworks the auto-instrumentation
-or simple configuration of a logging library to use an OpenTelemetry log appender
-will still be the easiest way to emit context-enriched logs. As
-already described earlier we provide extensions to some popular logging
-libraries languages to support the manual instrumentation cases. The extensions
-will support the inclusion of the trace context in the logs and allow to send
-logs using OTLP protocol to the backend or to the Collector, bypassing the need
-to have the logs represented as text files. Emitted logs are automatically
-augmented by application-specific resource context (e.g. process id, programming
-language, logging library name and version, etc). Full correlation across all
-context dimensions will be available for these logs.
+applications.
+
+Applications have several options for emitting logs:
+
+1. **Using existing logging libraries with OpenTelemetry log appenders**: For
+   applicable languages and frameworks, auto-instrumentation or simple
+   configuration of a logging library to use an OpenTelemetry log appender will
+   be the easiest way to emit context-enriched logs. As already described earlier,
+   we provide extensions to some popular logging libraries to support manual
+   instrumentation cases. The extensions support the inclusion of the trace
+   context in the logs and allow sending logs via OTLP protocol to the backend
+   or to the Collector, bypassing the need to have the logs represented as text
+   files.
+
+2. **Using the OpenTelemetry Logs API directly**: Applications can use the
+   [Logs API](./api.md) directly to emit structured logs and events. This approach
+   works well for emitting logs following [semantic conventions](https://opentelemetry.io/docs/specs/semconv/)
+   and enables easier reuse of attributes used across different signals. Note
+   that a language can provide a more convenient [ergonomic API](./api.md#ergonomic-api).
+
+Regardless of the approach, emitted logs are automatically augmented by
+application-specific resource context (e.g. process id, programming language,
+logging library name and version, etc). Full correlation across all context
+dimensions will be available for these logs.
 
 This is how a typical new application uses OpenTelemetry API, SDK and the
 existing log libraries:

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)