Skip to content

Commit

Permalink
Clarify spans export concurrency (open-telemetry#4205)
Browse files Browse the repository at this point in the history
Same as
open-telemetry#4173
for trace SDK.

Fixes
open-telemetry#4134
  • Loading branch information
pellared authored Sep 30, 2024
1 parent 6329081 commit 096df4a
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 7 deletions.
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))

### 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
requires of the exporter.

### 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
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`).
Expand Down

0 comments on commit 096df4a

Please sign in to comment.