Stabilize maxBatchSize for PeriodicMetricReader

[dashpole]

What are you trying to achieve?

Stabilize the maxBatchSize configuration option on PeriodicMetricReader, which was initially added in #4895.

This tracks the known blocking issues with the batching specification that need to be resolved prior to stabilization. Please report any issues or clarifications needed for the spec on this issue.

There are currently three experimental implementations:

• Go: Add experimental support for batching in periodic reader opentelemetry-go#8071
• Java: Add support for batching in PeriodicMetricReader opentelemetry-java#8296
• JS: feat(sdk-metrics): add maxExportBatchSize option to PeriodicExportingMetricReader opentelemetry-js#6655

Additional context.

Known Issues that must be resolved:

• Metrics: clarify and align PeriodicMetricReader export timeout semantics with batching spec opentelemetry-java#8311

_{Tip: React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

cc @psx95 @jack-berg

[dashpole]

I had an AI look through comment threads on the experimental implementation PRs and the java issue for ambiguity about how to apply the specification to the languages' existing batching behavior:

Cross-Language Findings & Ambiguities

1. exportTimeoutMillis Scope when Splitting into Batches

• Ambiguity: When maxExportBatchSize is configured and Collect() produces $M$ data points split into $N$ batches, does exportTimeoutMillis apply to each individual Export(batch) invocation, or does it apply across the entire scheduled cycle (Collect() + $N \times \text{Export()}`)?
• Language Findings:
  • Java (#8311, PR #8296): @jack-berg noted that the spec is ambiguous about whether the timeout applies to individual export requests or the collective batch, and that without explicit guidance, SDKs might rely solely on exporter network timeouts. @zeitlinger raised questions about reader-level timeout ownership during batched scheduled exports and ForceFlush().
  • Go (PR #8071): Applied timeout per individual Export(batch) call when batching (callWithTimeout(export(batch), timeout)). Reviewers discussed how to handle timeouts when Collect() is invoked directly vs. periodically via background ticker.
  • JS (PR #6655): Reviewers (@aabmass) asked if there is/should be a timeout for the overall Collect() + batch exports. @dashpole and @psx95 confirmed that exportTimeoutMillis in the spec applies to individual Export() calls.

2. Overlapping Cycles and Synchronization (Collect + Export)

• Ambiguity: The spec states: "The reader MUST synchronize calls to MetricExporter's Export to make sure that they are not invoked concurrently." However, it does not explicitly specify what happens if a periodic interval tick occurs while a previous multi-batch Export() cycle is still in progress.
• Language Findings:
  • JS (PR #6655): @psx95 and @dashpole noted that if an export hangs or times out without stopping background processing, subsequent interval ticks could trigger concurrent Collect() + Export() calls or out-of-order exports. @psx95 implemented logic to check the state of the current export and skip the new scheduled Collect() + Export cycle if an existing cycle is still running.
  • Java (PR #8296): Serialized export(batch) calls using asynchronous callbacks to ensure back-to-back batches within one cycle do not overlap, but also raised questions around concurrency between scheduled exports and manual forceFlush() invocations.

3. ForceFlush() Behavior with Batching and Timeouts

• Ambiguity: The spec states that ForceFlush SHOULD collect metrics, split into batches if necessary, and call Export(batch) on each batch followed by ForceFlush() on the exporter. It says ForceFlush MAY skip Export(batch) calls if the timeout expired, but SHOULD still call ForceFlush() on the exporter.
  • It does not explicitly specify whether exportTimeoutMillis applies to each individual Export(batch) inside ForceFlush(), or how partial batch failures/timeouts affect the return code of ForceFlush().
• Language Findings:
  • Java (#8311, PR #8296): @zeitlinger found a bug where individual batch export failures during ForceFlush() were tracked internally but forceFlush() still returned success. Java updated forceFlush() so that if any batch Export(batch) fails or times out, the outer forceFlush() returns failure (CompletableResultCode.fail()).
  • JS (PR #6655): @pichlermarc and @psx95 refined onForceFlush() so that if an export cycle is already in progress when ForceFlush() is called, it awaits that ongoing export before deciding whether to run a new cycle or immediately call exporter.forceFlush().

4. Serial Execution of Batches & Zero-Point Split Artifacts

• Ambiguity: Can batches from a single Collect() be exported concurrently, or must they be exported serially? Furthermore, when splitting metric data points across batches, could edge cases (such as a metric exact-filling a batch) result in empty/zero-point metric structures in subsequent batches?
• Language Findings:
  • JS (PR #6655): Confirmed that since the spec requires in-order delivery (MUST ensure all metric data points from a single Collect() are provided to Export before metric data points from a subsequent Collect() so that metric points are sent in-order), batches produced from one Collect() must be exported serially (one at a time).
  • Java (PR #8296) & JS (PR #6655): Both implementations encountered edge cases during splitting where a MetricData with 0 remaining points could be emitted or cause infinite loops if the current batch capacity was exactly 0.