Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify spans export concurrency #4205

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
pellared marked this conversation as resolved.
Show resolved Hide resolved

### Metrics

Expand Down
22 changes: 15 additions & 7 deletions specification/trace/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
pellared marked this conversation as resolved.
Show resolved Hide resolved
requires of the exporter.
pellared marked this conversation as resolved.
Show resolved Hide resolved

### Interface Definition

The exporter MUST support three functions: **Export**, **Shutdown**, and **ForceFlush**.
Expand All @@ -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
pellared marked this conversation as resolved.
Show resolved Hide resolved
same exporter instance.

pellared marked this conversation as resolved.
Show resolved Hide resolved
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`).
Expand Down
Loading