Why Exporter.ForceFlush and Exporter.Shutdown MUST be safe to be called concurrently?

[pellared]

I am unclear why concurrency responsibility for ForceFlush and Shutdown is assigned to LogRecordExporter.

In the standard SDK pipeline, exporter methods are invoked by processors rather than instrumentation code. The specification also says that minimizing the implementation burden for protocol exporters is a goal.

opentelemetry-specification/specification/logs/sdk.md

Lines 604 to 606 in b2180c6

	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.

In #4173, we placed responsibility for serializing Export on the built-in processors because restrictions on custom exporter implementations are difficult to enforce. Could the same model apply to all exporter methods?

Concretely, the specification could allow processors to serialize all calls to a given exporter instance (Export, ForceFlush, and Shutdown) and define whether sharing one exporter instance between processors is supported. Sharing already requires cross-processor coordination because Export is not expected to be invoked concurrently.

The OTel Go BatchProcessor now uses one worker for every exporter call and explicitly guarantees no overlap. The single-worker redesign also improved batch benchmarks (although those gains came from the broader removal of polling, buffering, and batch copying rather than serialization alone). The OTel Go SimpleProcessor would need corresponding lifecycle synchronization if responsibility were moved entirely to processors.

Since the same requirement exists for span and metric exporters, this likely needs a cross-signal decision. Could someone explain the use case requiring exporter implementations themselves, rather than their SDK callers, to provide lifecycle concurrency safety? It would also help to define which combinations of Export, ForceFlush, and Shutdown are intended to overlap, if any.

Originally posted by @pellared in #4885

[pellared]

@trask, @reyang, @tigrannajaryan, @MrAlias, @dashpole, @cijothomas, PTAL

[pellared]

From Codex:

I think the intuition that this coordination belongs in the batch processor is mostly correct, with one important qualification.

There are two different queues or stages involved:

telemetry -> processor queue/batching -> Export(batch) -> exporter transport/retry work -> backend

The batch processor owns the first stage. It decides when to export, creates batches, drains its queue during ForceFlush, and can serialize the calls it makes to one exporter instance. An exporter should not need to recreate that SDK-level batching machinery.

The exporter owns the second stage. Once it has accepted a batch, it may still have an asynchronous network request, protocol-specific retry, or transport cleanup in progress. The specification explicitly assigns concurrent requests and retry logic to exporters rather than processors. This is different from the telemetry batching performed by the batch processor.

Consequently, a complete processor ForceFlush has two barriers:

1. Drain telemetry that is still waiting in the processor.
2. Finish work already accepted by the exporter.

This is reflected in the current specification. Built-in span processors and log processors are required to export their pending telemetry and then invoke the exporter's ForceFlush; the periodic metric reader has the same two-stage requirement. If an export operation completes only after delivery or final failure, and the processor waits for that completion, the second barrier can be a no-op. That is a valid and common exporter implementation.

The exporter interface is also used by simple and custom processors, not only by the batch processor. That may explain why the specification chose a broad exporter-side guarantee. It does not prove that the guarantee is necessary, however: a simple processor can use an admission gate and track in-flight exports without implementing telemetry batching.

What this does—and does not—justify

The downstream stage means an exporter has to coordinate ForceFlush or Shutdown with its own previously accepted work. It does not necessarily mean that the SDK must be allowed to invoke Export, ForceFlush, and Shutdown concurrently.

Those are separate properties:

• Internal-operation safety: an exporter can safely flush or shut down while an earlier asynchronous export operation remains in flight.
• Concurrent-invocation safety: multiple callers may enter exporter methods at the same time.

The first property is necessary for an asynchronous exporter. The second is a calling-convention decision and can instead be provided by the processor or reader.

For example, suppose Export returns a future immediately and the network operation finishes later. The specification explicitly permits this separation between an invocation and its asynchronous task. Calling Shutdown only after the Export method has returned does not prevent the two operations from overlapping. The processor has to await the export result—or the exporter has to coordinate shutdown with the pending operation. A mutex that merely prevents simultaneous method entry does not solve that problem.

This distinction is especially visible in JavaScript: method invocations run sequentially on the event loop, while the promises returned by those methods can overlap. The current phrase “safe to be called concurrently” does not say which of these it means.

Evidence from existing SDKs

Both responsibility models exist today:

• Go's log BatchProcessor, Rust's default batch processor, and PHP's trace processor largely give one worker or queue ownership of exporter calls. They demonstrate that processor-side sequencing is implementable.
• .NET intentionally serializes Export in the processor while its exporter base type makes lifecycle operations thread-safe.
• Go metrics, and parts of Java, Python, and Ruby, also allow lifecycle calls to occur outside the lock or worker that serializes exports.
• JavaScript logs deliberately permit some asynchronous export and lifecycle work to overlap.

Therefore, replacing the exporter requirement with a new processor requirement would not merely clarify existing behavior; it would select one of several deployed models.

Sharing is a separate ownership problem

A processor-local lock cannot coordinate one exporter instance shared by two processors or readers. More importantly, sharing makes lifecycle ownership unclear: if one processor shuts the exporter down, the other processor can no longer use it.

I think the simplest default would be exclusive ownership: an exporter instance is owned by one processor or reader unless the language implementation explicitly documents sharing. When sharing is supported, the exporter or a shared wrapper must provide the cross-owner coordination.

This would avoid imposing sharing costs on every exporter merely because the specification is currently silent about ownership.

Suggested resolution

I would refine the earlier conclusion as follows:

An exporter must safely coordinate lifecycle operations with asynchronous work it has already accepted. This does not by itself require the SDK to invoke exporter methods concurrently.

For an exclusively owned exporter, built-in processors and readers could be required to provide a defined ordering:

1. Serialize or otherwise sequence exporter operations, including their async completion—not merely synchronous method entry.
2. On ForceFlush, drain the processor queue and then complete exporter work accepted before the flush boundary.
3. Once Shutdown begins, admit no new exports; drain or cancel previously accepted work according to the timeout.
4. Perform one logical shutdown and define what concurrent/repeated callers observe.
5. State explicitly whether sharing an exporter instance is supported.

The exporter would remain responsible for protocol-specific retries, transport state, and safe cleanup of its own in-flight work. Its ForceFlush may be a no-op when completion of Export already provides the required barrier.

This division better matches the stated goal of minimizing exporter burden. It also avoids the ambiguous claim that all lifecycle methods must accept concurrent invocation when the actual requirement may only be correct ordering with asynchronous work.

Because the current concurrency requirements are Stable and SDKs implement different models, changing the responsibility should be treated as a cross-signal stability change and validated with prototypes in several language models.

[dashpole]

Just to clarify, export was defined as serial to make it easier for vendors to implement (original discussion threads are in #186), not because it is difficult to enforce. The fact that it is difficult to enforce just means it is enforced via documentation instead of programmatically.

I generally see the burden of proof as the inverse: I would require methods on plugin interfaces to be safe to be called concurrently unless there is a good reason not to. The cost of a simple mutex is generally low compared to exporting a big batch of telemetry. Is this really beneficial for log exporters that synchronously write logs one-at-a-time or something like that?

In terms of backwards-compatibility, SDKs could serialize all calls it makes to exporters without it being breaking, and we could remove the documentation requirements, but existing stable (e.g. OTLP) exporters can't remove their concurrent-safety without a new major version.