From 3f414f025964be64ec621ed556c483318c174f75 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 19 Nov 2025 09:52:54 +0100 Subject: [PATCH 1/8] [Logs] Add optional Ergonomic API --- CHANGELOG.md | 3 +++ specification/logs/api.md | 20 ++++++++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 706631559a4..5b1c043112f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Add optional Ergonomic API. + ([#ABC](https://github.com/open-telemetry/opentelemetry-specification/pull/ABC)) + ### Baggage ### Profiles diff --git a/specification/logs/api.md b/specification/logs/api.md index 66eb9c6b995..87ed978ee8e 100644 --- a/specification/logs/api.md +++ b/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
Table of Contents @@ -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) @@ -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 +[general log semantics](https://opentelemetry.io/docs/specs/semconv/general/logs/#general-log-semantics) +and the [general event semantics](https://opentelemetry.io/docs/specs/semconv/general/events/#general-event-semantics). + +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) From 62a752d670afc250355c25de04ea40a4bf0b0ff3 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 19 Nov 2025 10:01:30 +0100 Subject: [PATCH 2/8] Update changelog entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b1c043112f..e5c0a803b25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ release. ### Logs - Add optional Ergonomic API. - ([#ABC](https://github.com/open-telemetry/opentelemetry-specification/pull/ABC)) + ([#4741](https://github.com/open-telemetry/opentelemetry-specification/pull/4741)) ### Baggage From 99bb74a1b2b11e7535b439e46aa9ae22794ad55c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 19 Nov 2025 10:06:08 +0100 Subject: [PATCH 3/8] Update api.md --- specification/logs/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 87ed978ee8e..1fb8793a2fc 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -178,8 +178,8 @@ 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 -[general log semantics](https://opentelemetry.io/docs/specs/semconv/general/logs/#general-log-semantics) -and the [general event semantics](https://opentelemetry.io/docs/specs/semconv/general/events/#general-event-semantics). +[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. From 813996486e6a71eb0a7092c299180089a6a9b47e Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Wed, 19 Nov 2025 10:16:46 +0100 Subject: [PATCH 4/8] Update spec compliance matrix --- .gitignore | 3 +++ spec-compliance-matrix.md | 1 + spec-compliance-matrix/template.yaml | 2 ++ 3 files changed, 6 insertions(+) diff --git a/.gitignore b/.gitignore index 7aadede2c9e..f8b1a862c5e 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,9 @@ internal/tools/bin node_modules/ package-lock.json +# Python virtual environment +venv/ + # Visual Studio Code .vscode diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 60e47a8c4c5..683ad5686b9 100644 --- a/spec-compliance-matrix.md +++ b/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 | | + | + | + | + | + | | + | | + | | | diff --git a/spec-compliance-matrix/template.yaml b/spec-compliance-matrix/template.yaml index d3eb46a334b..efab0f2de3c 100644 --- a/spec-compliance-matrix/template.yaml +++ b/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 From d3f5fb68fb134c0928b8ef0f44b4c919a4181327 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 20 Nov 2025 13:55:36 +0100 Subject: [PATCH 5/8] Update OpenTelemetry Logging readme --- specification/logs/README.md | 58 ++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index a1c0d04a16a..c7e22c9672f 100644 --- a/specification/logs/README.md +++ b/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 (e.g., string formatting, log levels) than what is defined in + OpenTelemetry. Yet, languages may provide a more 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 and ergonomic logging interface. + +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: From 4e5a19843d73ff3063feb526531e8db0085d5492 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 20 Nov 2025 13:57:31 +0100 Subject: [PATCH 6/8] Update README.md --- specification/logs/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index c7e22c9672f..3e622e036fb 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -156,9 +156,8 @@ Given the above state of the logging space we took the following approach: intermediary logging frameworks. Note that existing logging libraries generally provide a much richer set of - features (e.g., string formatting, log levels) than what is defined in - OpenTelemetry. Yet, languages may provide a more ergonomic API for better - developer experience when using it directly. + features than what is defined in OpenTelemetry. Yet, languages may provide + a more 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) From fe8c5fe708eeabf32bc2f2a4980325bf2750fdeb Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 20 Nov 2025 14:05:04 +0100 Subject: [PATCH 7/8] add hyperlinks --- specification/logs/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index 3e622e036fb..7e83f76f298 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -157,7 +157,8 @@ Given the above state of the logging space we took the following approach: Note that existing logging libraries generally provide a much richer set of features than what is defined in OpenTelemetry. Yet, languages may provide - a more ergonomic API for better developer experience when using it directly. + 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) @@ -399,7 +400,7 @@ Applications have several options for emitting logs: [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 and ergonomic logging interface. + 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, From b10da753b82ed96ed5380da60a16103f05f41af6 Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Thu, 20 Nov 2025 20:23:25 +0100 Subject: [PATCH 8/8] apply suggestion --- specification/logs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index 7e83f76f298..ca64e4f237e 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -152,8 +152,9 @@ Given the above state of the logging space we took the following approach: - **Instrumentation libraries** to avoid coupling to a particular logging library. - **Emitting structured logs and events** following [semantic conventions](https://opentelemetry.io/docs/specs/semconv/), + especially when the existing logging library cannot emit structured data or specify event names. - **Scenarios requiring direct control** over log emission without - intermediary logging frameworks. + intermediary logging library. Note that existing logging libraries generally provide a much richer set of features than what is defined in OpenTelemetry. Yet, languages may provide