From ec39f1b0d98e2ddd694e74016bc58b39ccc27120 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 23 Feb 2024 09:41:26 +0100 Subject: [PATCH 1/4] Redefine ReadableLogRecord and ReadWriteLogRecord --- specification/logs/sdk.md | 68 ++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 36 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 0cef89a29bd..e5a6442ddc6 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,6 +7,9 @@ +- [Definitions Used in this Document](#definitions-used-in-this-document) + * [ReadableLogRecord](#readablelogrecord) + * [ReadWriteLogRecord](#readwritelogrecord) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -14,9 +17,6 @@ * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Logger](#logger) -- [Additional LogRecord interfaces](#additional-logrecord-interfaces) - * [ReadableLogRecord](#readablelogrecord) - * [ReadWriteLogRecord](#readwritelogrecord) - [LogRecord Limits](#logrecord-limits) - [LogRecordProcessor](#logrecordprocessor) * [LogRecordProcessor operations](#logrecordprocessor-operations) @@ -43,6 +43,35 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. +## Definitions Used in this Document + +In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord` defined as follows. + +### ReadableLogRecord + +A function receiving this as an argument MUST be able to access all the +information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to +access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) +and [Resource](./data-model.md#field-resource) information (implicitly) +associated with the `LogRecord`. + +The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from +the resolved `Context` (either the explicitly passed `Context` or the +current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). + +Counts for attributes due to collection limits MUST be available for exporters +to report as described in +the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) +specification. + +### ReadWriteLogRecord + +A function receiving this as an argument MUST be able to write to the +full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all +information +that was added to the `LogRecord` (as with +[ReadableLogRecord](#readablelogrecord)). + ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) @@ -127,39 +156,6 @@ registered [LogRecordProcessors](#logrecordprocessor). Note that `Logger`s should not be responsible for configuration. This should be the responsibility of the `LoggerProvider` instead. -## Additional LogRecord interfaces - -In addition to the [definition for LogRecord](data-model.md#log-and-event-record-definition), the -following `LogRecord`-like interfaces are defined in the SDK: - -### ReadableLogRecord - -A function receiving this as an argument MUST be able to access all the -information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to -access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) -and [Resource](./data-model.md#field-resource) information (implicitly) -associated with the `LogRecord`. - -The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from -the resolved `Context` (either the explicitly passed `Context` or the -current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). - -Counts for attributes due to collection limits MUST be available for exporters -to report as described in -the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) -specification. - -Note: Typically this will be implemented with a new interface or (immutable) -value type. - -### ReadWriteLogRecord - -A function receiving this as an argument MUST be able to write to the -full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all -information -that was added to the `LogRecord` (as with -[ReadableLogRecord](#readablelogrecord)). - ## LogRecord Limits `LogRecord` attributes MUST adhere to From b6a24712d18dddfbe0509b0b35c9eafab924f2a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 13 Mar 2024 08:29:03 +0100 Subject: [PATCH 2/4] Update sdk.md --- specification/logs/sdk.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index e5a6442ddc6..caa278582fa 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -64,6 +64,9 @@ to report as described in the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) specification. +Note: Typically this will be implemented with a new interface or (immutable) +value type. + ### ReadWriteLogRecord A function receiving this as an argument MUST be able to write to the From 635ca75902f0fbbf80f6d7cba49ad1e5c5e8c397 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 13 Mar 2024 08:48:25 +0100 Subject: [PATCH 3/4] Update sdk.md --- specification/logs/sdk.md | 71 ++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index caa278582fa..e2bffc731e7 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,9 +7,6 @@ -- [Definitions Used in this Document](#definitions-used-in-this-document) - * [ReadableLogRecord](#readablelogrecord) - * [ReadWriteLogRecord](#readwritelogrecord) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -17,6 +14,9 @@ * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Logger](#logger) +- [Additional LogRecord interfaces](#additional-logrecord-interfaces) + * [ReadableLogRecord](#readablelogrecord) + * [ReadWriteLogRecord](#readwritelogrecord) - [LogRecord Limits](#logrecord-limits) - [LogRecordProcessor](#logrecordprocessor) * [LogRecordProcessor operations](#logrecordprocessor-operations) @@ -43,38 +43,6 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. -## Definitions Used in this Document - -In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord` defined as follows. - -### ReadableLogRecord - -A function receiving this as an argument MUST be able to access all the -information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to -access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) -and [Resource](./data-model.md#field-resource) information (implicitly) -associated with the `LogRecord`. - -The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from -the resolved `Context` (either the explicitly passed `Context` or the -current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). - -Counts for attributes due to collection limits MUST be available for exporters -to report as described in -the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) -specification. - -Note: Typically this will be implemented with a new interface or (immutable) -value type. - -### ReadWriteLogRecord - -A function receiving this as an argument MUST be able to write to the -full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all -information -that was added to the `LogRecord` (as with -[ReadableLogRecord](#readablelogrecord)). - ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) @@ -159,6 +127,39 @@ registered [LogRecordProcessors](#logrecordprocessor). Note that `Logger`s should not be responsible for configuration. This should be the responsibility of the `LoggerProvider` instead. +## Additional LogRecord interfaces + +In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord`, defined as follows. + +### ReadableLogRecord + +A function receiving this as an argument MUST be able to access all the +information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to +access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) +and [Resource](./data-model.md#field-resource) information (implicitly) +associated with the `LogRecord`. + +The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from +the resolved `Context` (either the explicitly passed `Context` or the +current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). + +Counts for attributes due to collection limits MUST be available for exporters +to report as described in +the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count) +specification. + +Note: Typically this will be implemented with a new interface or (immutable) +value type. The SDK may also use a single type to represent both `ReadableLogRecord` +and `ReadWriteLogRecord`. + +### ReadWriteLogRecord + +A function receiving this as an argument MUST be able to write to the +full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all +information +that was added to the `LogRecord` (as with +[ReadableLogRecord](#readablelogrecord)). + ## LogRecord Limits `LogRecord` attributes MUST adhere to From 7b8bf5afe9489e654aad802a52116fefe9411a0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 13 Mar 2024 08:53:15 +0100 Subject: [PATCH 4/4] Update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d79247f37de..cdf0575ced1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,8 @@ release. ([#3853](https://github.com/open-telemetry/opentelemetry-specification/pull/3853)) - Mark standard output log record exporter as stable. ([#3922](https://github.com/open-telemetry/opentelemetry-specification/pull/3922)) +- Clarify that `ReadableLogRecord` and `ReadWriteLogRecord` can be represented using a single type. + ([#3898](https://github.com/open-telemetry/opentelemetry-specification/pull/3898)) ### Resource