Align `export_timeout_millis` across SDK components

[tammy-baylis-swi]

Context

Recent discussion over #5650 and #4555 (and several older issues) exposed inconsistent semantics and usage for export_timeout_millis across the Python SDK. The setting appears in the batch span processor, periodic metric reader, and batch log processor, but it is not consistently enforced nor used to bound export work. It would be great to identify current behaviour and establish a consistent direction before making potential changes.

Scope

Review and compare:

• BatchSpanProcessor
• PeriodicExportingMetricReader
• BatchLogRecordProcessor
• OTLP exporters and their timeout parameters
• Related environment-variable configuration, including OTEL_BSP_EXPORT_TIMEOUT

Also compare the current Python behaviour with the relevant trace, metrics, and logs SDK specifications. Check whether any spec/semconv defines or constrains these configuration values. Note that inconsistencies are likely due to Python SDK implementation completion before spec/semconv was established.

Known facts

• The SDK configuration is named export_timeout_millis / exportTimeoutMillis, by the trace and log processor implementations and trace SDK specification, so they describe milliseconds.
• The trace batching specification describes a default of 30000 ms and defines the value as how long an export may run before it is cancelled.
  • The logs batching specification uses the same exportTimeoutMillis concept and default of 30000 ms.
• The metrics periodic exporting specification defines exportTimeoutMillis with a default of 30000 ms. It applies to export calls, including each export invocation when a collection is split into multiple batches.
• The Python periodic metric reader passes its configured timeout to metric collection, where it can bound metric collection and asynchronous callbacks; this is not necessarily identical to bounding the exporter call.
• Python's exporter interfaces generally do not support a processor-supplied timeout argument. Some OTLP exporters have their own timeout configuration, commonly represented as a floating-point value in seconds rather than an integer number of milliseconds.
• In the current Python shared batch processor implementation, export_timeout_millis is stored but is not currently passed to or used to cancel the export operation. Consequently, for span and log processors, changing this value currently has no runtime effect on an in-flight export.
• Issue #4555 confirms that the metrics path has the same practical gap: the configured timeout is passed through to export, but the OTLP gRPC metric exporter and OTLP HTTP metric exporter ignore it.
• The shared batch processor implementation does not currently provide a general mechanism to cancel synchronous exporter work once it has started.
• Existing trace and log validation has been inconsistent: non-positive values were historically accepted by some or all of these components, even though related queue and scheduling parameters require positive values. Issue #5648 and Issues #5655 track portions of this validation problem.
• math.inf is already used in the periodic metric reader to represent continuous or effectively unbounded scheduling in some contexts, but its meaning for an export timeout has not been established consistently.

Related open issues and prior discussions

See project board: Python: Align export_timeout_millis across SDK (view)

Unknowns / decisions needed

1. What does the timeout govern?

   • Time spent collecting data/calling asynchronous callbacks.
   • Time spent in Exporter.export.
   • The entire processor export operation, including queue handling and completion of asynchronous work.
   • Whether the definition should be identical for traces, metrics, and logs.

2. How should cancellation work in Python?

   • Is a timeout only a deadline after which the SDK records a timeout and proceeds?
   • Must the SDK cancel/interrupt the exporter operation when possible?
   • How should synchronous exporters, thread-based exporters, async exporters, gRPC, and HTTP exporters differ?
   • Can the SDK safely continue with another export while a timed-out export is still running?

3. What should values mean?

   • 0: invalid value, immediate timeout, or disable timeout?
   • Negative values: invalid, or another sentinel for no timeout?
   • math.inf: valid unlimited timeout, equivalent to no deadline, or invalid because it cannot be represented by all underlying APIs?
   • None: default value, no timeout, or an implementation-only sentinel?

4. What type and unit should the Python API use?

   • Preserve the spec-facing integer milliseconds (int).
   • Accept a float in milliseconds to match existing Python typing and configuration behavior.
   • Use seconds as a Python runtime value, converting at the SDK boundary.
   • Use a duration type or deadline abstraction internally while retaining milliseconds in the public configuration surface.

5. How do SDK and exporter timeouts interact?

   • Define precedence between export_timeout_millis, OTLP exporter timeout settings, and OTEL_EXPORTER_OTLP_TIMEOUT.
   • Avoid silently converting milliseconds to seconds or passing a processor timeout under an exporter parameter with a different unit/name.
   • Decide whether the processor timeout should be passed to exporters at all, or remain independent as specified by the SDK.
   • Issue #4555 specifically identifies the unresolved case where an OTLP exporter timeout is already set through another environment variable.

6. Cross-signal and cross-language consistency

   • Confirm whether the current specifications intentionally require the same semantics for span, metric, and log components.
   • Compare how other language SDKs interpret zero, infinity, cancellation, and timeout expiry.
   • Identify any required specification clarification or semantic-conventions change. Semantic conventions appear unrelated to SDK control-plane configuration, but this should be confirmed rather than assumed.

Proposed investigation

• Build a behavior matrix for span, metric, and log components covering positive values, 0, negative values, math.inf, None, slow collection, slow export, exporter failure, force flush, and shutdown.
• Trace each value from environment-variable parsing through constructor validation, internal storage, collection/export invocation, and shutdown.
• Once direction is agreed, identify and split implementation work.