diff --git a/CHANGELOG.md b/CHANGELOG.md index 5229633bdba..20ec4667979 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. - Make all fields as identifying for Tracer. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- Clarify that `Export` MUST NOT be called by simple and batching processors concurrently. + ([#4205](https://github.com/open-telemetry/opentelemetry-specification/pull/4205)) ### Metrics diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e406db86ddd..07755ca56dd 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -693,6 +693,9 @@ This is an implementation of `SpanProcessor` which passes finished spans and passes the export-friendly span data representation to the configured `SpanExporter`, as soon as they are finished. +The processor MUST synchronize calls to `Span Exporter`'s `Export` +to make sure that they are not invoked concurrently. + **Configurable parameters:** * `exporter` - the exporter where the spans are pushed. @@ -703,9 +706,11 @@ This is an implementation of the `SpanProcessor` which create batches of finishe spans and passes the export-friendly span data representations to the configured `SpanExporter`. +The processor MUST synchronize calls to `Span Exporter`'s `Export` +to make sure that they are not invoked concurrently. + The processor SHOULD export a batch when any of the following happens AND the -previous export call has returned (for additional concurrency details see -the [Export() specification](#exportbatch)): +previous export call has returned: - `scheduledDelayMillis` after the processor is constructed OR the first span is received by the span processor. @@ -742,6 +747,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. + ### Interface Definition The exporter MUST support three functions: **Export**, **Shutdown**, and **ForceFlush**. @@ -755,15 +763,15 @@ 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 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 -while an instance of an exporter will never have its Export() called +while an instance of an exporter should never have its 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. +concurrently. How 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`).