diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e25484d4e1..f60d59a491d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ release. ### Traces +- Clarify the return of `Export(batch)` in the Batch Span Processor and exporter + concurrency ([#2452](https://github.com/open-telemetry/opentelemetry-specification/pull/2452)) + ### Metrics - Add experimental `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` variable for diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index a1970c90743..e3f3a9570ee 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -615,15 +615,24 @@ 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() can be called again only after the current call returns. +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 +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. Export() MUST NOT block indefinitely, there MUST be a reasonable upper limit after which the call must time out with an error result (`Failure`). -Any retry logic that is required by the exporter is the responsibility -of the exporter. The default SDK SHOULD NOT implement retry logic, as -the required logic is likely to depend heavily on the specific protocol -and backend the spans are being sent to. +Concurrent requests and retry logic is the responsibility of the exporter. The +default SDK's Span Processors SHOULD NOT implement retry logic, as the required +logic is likely to depend heavily on the specific protocol and backend the spans +are being sent to. For example, the [OpenTelemetry Protocol (OTLP) +specification](../protocol/otlp.md) +defines logic for both sending concurrent requests and retrying requests. **Parameters:** @@ -633,7 +642,9 @@ e.g. for spans in Java it will be typically `Collection`. **Returns:** ExportResult: -ExportResult is one of: +The return of Export() is implementation specific. In what is idiomatic for the +language the Exporter must send an `ExportResult` to the Processor. +`ExportResult` has values of either `Success` or `Failure`: * `Success` - The batch has been successfully exported. For protocol exporters this typically means that the data is sent over @@ -641,8 +652,10 @@ ExportResult is one of: * `Failure` - exporting failed. The batch must be dropped. For example, this can happen when the batch contains bad data and cannot be serialized. -Note: this result may be returned via an async mechanism or a callback, if that -is idiomatic for the language implementation. +For example, in Java the return of Export() would be a Future which when +completed returns the `ExportResult` object. While in Erlang the Exporter sends +a message to the Processor with the `ExportResult` for a particular batch of +spans. #### `Shutdown()`