/ 
OpenTelemetry-SDK-0.029-TRIAL
⭐ Starred 9 / OpenTelemetry::Processor::Batch

NAME

OpenTelemetry::Processor::Batch - A base class for OpenTelemetry batch processors

SYNOPSIS

...

DESCRIPTION

This is a base class for processors that operate on batches of records. It is intended to implement the core behaviours that are needed regardless of whether this is processing trace spans, log records, or metrics.

This processor is intended to be used in production environments where performance is important. It will maintain a queue of records to export, and periodically exports these in batches in a parallel process, which should allow the main process to continue executing without any delay added by the export step.

The worker processes that do the exporting run in a IO::Async::Function and will therefore use whatever event loop is returned by IO::Async::Loop. Please refer to the documentation of those modules for details on how to control this.

METHODS

This class implements the OpenTelemetry::Processor role. Please consult that module's documentation for details on the behaviours it provides.

new

$processor = OpenTelemetry::Processor::Batch->new(
    exporter         => $span_exporter,
    batch_size       => $batch_size // OTEL_BSP_MAX_EXPORT_BATCH_SIZE,
    exporter_timeout => $timeout    // OTEL_BSP_EXPORT_TIMEOUT,
    max_queue_size   => $queue_size // OTEL_BSP_MAX_QUEUE_SIZE,
    schedule_delay   => $delay      // OTEL_BSP_SCHEDULE_DELAY,
);

The constructor takes a mandatory exporter parameter that must be set to an instance of a class that implements the OpenTelemetry::Exporter role.

It also accepts the following optional parameters:

batch_size

The size of the batch of spans to send to the exporter. If not set, this will read the default value from the "OTEL_BSP_MAX_EXPORT_BATCH_SIZE" environment variable, which in turn defaults to 512.

exporter_timeout

The number of milliseconds to send to "export" in OpenTelemetry::Exporter. If not set, this will read the default value from the "OTEL_BSP_EXPORT_TIMEOUT" environment variable, which in turn defaults to 30000.

max_queue_size

The maximum size of the internal queue. If not set, this will read the default value from the "OTEL_BSP_MAX_QUEUE_SIZE" environment variable, which in turn defaults to 2048.

If an attempt is made to queue a record when the queue is full, the older records will be removed from the queue until there is enough space for the newer ones. If this happens, the code will call "report_dropped" with the buffer-full reason and the number of records that were dropped.

schedule delay

The minimum delay in milliseconds between calls to "export" in OpenTelemetry::Exporter. If not set, this will read the default value from the "OTEL_BSP_SCHEDULE_DELAY" environment variable, which in turn defaults to 5000.

Note: this is not yet implemented.

process

$processor->process( @records );

Takes a list of records that are ready for processing. Once called, this method will queue them for eventual processing. Once enough records have been queued, a batch of them will be sent to the configured exporter.

Since this processor works only when a batch is ready, it can sometimes make for more complicated debugging. For a simpler processor that handles each record as it becomes ready and blocks during the export step, see OpenTelemetry::Processor::Simple.

report_dropped

$processor = $processor->report_dropped( $reason, $count );

Reports the number of dropped records for the specified reason. The reason must be usable as a string, and the count must be usable as a number.

The method in this class does nothing, but subclasses can extend it.

This method returns the calling instance, and is suitable for chaining.

report_result

$result = $processor->report_result( $result, $count );

Takes an export result and the number of records that that result applies to, and reports this result.

It returns the export result, so it is suitable to be used when returning from an exporting function.

The method in this class does nothing. It is expected to be extended by subclasses.

force_flush

$result = await $processor->force_flush( $timeout );

Empties the internal queue by sending any unexported records to the exporter.

Takes an optional timeout in seconds. If this has been set, any records remaining after the time has run out will be dropped and the number of dropped spans will be reported with "report_dropped" with the force-flush reason.

This method will also call "force_flush" on the configured exporter. It returns a Future that will hold the result of that operation.

shutdown

$result = await $processor->shutdown( $timeout );

Calls "shutdown" on the configured exporter and returns a Future that will hold the result of that operation.

Once the processor has been shutdown, any additional calls to "shutdown", "force_flush" will do nothing and immediately return a success result.

METRICS

This processor generates the metrics described below as part of its operation. At the time of writing, these metrics are non-standard, but their inclusion in the standard is being discussed.

Metrics are reported using Metrics::Any. Please consult the documentation of that module to learn how to redirect where they are sent to.

otel.processor.batch.buffer_use

Set to the size of the internal queue divided by the "max_queue_size" immediately before a batch is picked up for processing.

SEE ALSO

Future
IO::Async::Function
IO::Async::Loop.
Metrics::Any
OpenTelemetry::Constants
OpenTelemetry::Exporter
OpenTelemetry::Processor
OpenTelemetry::Processor::Simple

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.