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/CHANGELOG.md b/CHANGELOG.md index 7ad8acd3c28..406195cb969 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,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 diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 5c7431693bd..67e3ce5de6e 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 82078059256..d42cceb86e3 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 diff --git a/specification/logs/README.md b/specification/logs/README.md index a1c0d04a16a..ca64e4f237e 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -143,15 +143,23 @@ 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/), + especially when the existing logging library cannot emit structured data or specify event names. + - **Scenarios requiring direct control** over log emission without + 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 + 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 +383,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: diff --git a/specification/logs/api.md b/specification/logs/api.md index 66eb9c6b995..1fb8793a2fc 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 +[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)