span exporter concurrency: expand on Export() requirements (#2452)

Author: tsloughter

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

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,16 +642,20 @@ e.g. for spans in Java it will be typically `Collection<SpanData>`.
 
 **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
   the wire and delivered to the destination server.
 * `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()`