From a2262e0661712f6c45d01f81cac4ed6b919733a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 1 Aug 2024 11:05:02 +0200 Subject: [PATCH 1/5] Clarify logs export concurrency --- specification/logs/sdk.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index eadd5a597d2..d72cf2eded2 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -396,6 +396,9 @@ passes the export-friendly `ReadableLogRecord` representation to the configured [LogRecordExporter](#logrecordexporter), as soon as they are finished. +The processor MUST synchronize calls to `LogRecordExporter`'s `Export` +to make sure that they are not executed in parallel. + **Configurable parameters:** * `exporter` - the exporter where the `LogRecord`s are pushed. @@ -406,6 +409,9 @@ This is an implementation of the `LogRecordProcessor` which create batches of `LogRecord`s and passes the export-friendly `ReadableLogRecord` representations to the configured `LogRecordExporter`. +The processor MUST synchronize calls to `LogRecordExporter`'s `Export` +to make sure that they are not executed in parallel. + **Configurable parameters:** * `exporter` - the exporter where the `LogRecord`s are pushed. @@ -443,6 +449,9 @@ The goal of the interface is to minimize burden of implementation for protocol-dependent telemetry exporters. The protocol exporter is expected to be primarily a simple telemetry data encoder and transmitter. +Each implementation MUST document the concurrency characteristics the SDK +requires of the exporter. + ### LogRecordExporter operations A `LogRecordExporter` MUST support the following functions: @@ -453,14 +462,13 @@ Exports a batch of [ReadableLogRecords](#readablelogrecord). Protocol exporters that will implement this function are typically expected to serialize and transmit the data to the destination. -`Export` will never be called concurrently for the same exporter instance. +`Export` should not be called concurrently for the same exporter instance. Depending on the implementation the result of the export may be returned to the Processor not in the return value of the call to `Export` but in a language specific way for signaling completion of an asynchronous task. This means that -while an instance of an exporter will never have it `Export` called concurrently +while an instance of an exporter should never have it `Export` called concurrently it does not mean that the task of exporting can not be done concurrently. How -this is done is outside the scope of this specification. Each implementation -MUST document the concurrency characteristics the SDK requires of the exporter. +this is done is outside the scope of this specification. `Export` MUST NOT block indefinitely, there MUST be a reasonable upper limit after which the call must time out with an error result (`Failure`). From 019324be226450243c3d85782778b7ef4aaa9a20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 1 Aug 2024 11:07:24 +0200 Subject: [PATCH 2/5] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e71b526382..8e6a8508098 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,8 @@ release. - The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`. ([#4090](https://github.com/open-telemetry/opentelemetry-specification/pull/4090)) +- Clarify that `Export` MUST NOT be called by simple and batching processors concurrently. + ([#4173](https://github.com/open-telemetry/opentelemetry-specification/pull/4173)) ### Events From 90b38bca4f97efe2da00eda832359acfc27cedfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 1 Aug 2024 13:48:20 +0200 Subject: [PATCH 3/5] Clarify --- specification/logs/sdk.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index d72cf2eded2..0cc27673921 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -462,7 +462,9 @@ Exports a batch of [ReadableLogRecords](#readablelogrecord). Protocol exporters that will implement this function are typically expected to serialize and transmit the data to the destination. -`Export` should not be called concurrently for the same exporter instance. +`Export` should not be called concurrently with other `Export` calls for the +same exporter instance. + Depending on the implementation the result of the export may be returned to the Processor not in the return value of the call to `Export` but in a language specific way for signaling completion of an asynchronous task. This means that From 88a6ca71e0cd5020dc365a1be8a0256865a340a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Sat, 24 Aug 2024 07:28:19 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Cijo Thomas --- specification/logs/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 0cc27673921..7064fc16ec9 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -397,7 +397,7 @@ configured [LogRecordExporter](#logrecordexporter), as soon as they are finished. The processor MUST synchronize calls to `LogRecordExporter`'s `Export` -to make sure that they are not executed in parallel. +to make sure that they are not invoked in parallel. **Configurable parameters:** @@ -410,7 +410,7 @@ of `LogRecord`s and passes the export-friendly `ReadableLogRecord` representations to the configured `LogRecordExporter`. The processor MUST synchronize calls to `LogRecordExporter`'s `Export` -to make sure that they are not executed in parallel. +to make sure that they are not invoked in parallel. **Configurable parameters:** From ad2fa5bd85541873ab58b60fe489133c81095891 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 5 Sep 2024 11:21:00 +0200 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Reiley Yang --- specification/logs/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 7064fc16ec9..7f7f201691f 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -397,7 +397,7 @@ configured [LogRecordExporter](#logrecordexporter), as soon as they are finished. The processor MUST synchronize calls to `LogRecordExporter`'s `Export` -to make sure that they are not invoked in parallel. +to make sure that they are not invoked concurrently. **Configurable parameters:** @@ -410,7 +410,7 @@ of `LogRecord`s and passes the export-friendly `ReadableLogRecord` representations to the configured `LogRecordExporter`. The processor MUST synchronize calls to `LogRecordExporter`'s `Export` -to make sure that they are not invoked in parallel. +to make sure that they are not invoked concurrently. **Configurable parameters:**