NAME

OpenTelemetry::SDK::Trace::Span::Processor::Batch - A batched OpenTelemetry span processor

SYNOPSIS

...

DESCRIPTION

This is a batched span processor that receives read-only OpenTelemetry::Trace::Span instances and forwards them to an exporter as readable instances of OpenTelemetry::SDK::Trace::Span::Readable.

This processor is intended to be used in production environments where performance is important. It will maintain a queue of spans 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 exporting the spans.

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::Trace::Span::Processor role. Please consult that module's documentation for details on the behaviours it provides.

new

$processor = OpenTelemetry::SDK::Trace::Processor::Simple->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 span 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 span when the queue is full, the older spans will be removed from the queue until there is enough space for the newer spans. The number of dropped spans will be reported to the otel.bsp.spans.dropped metric with the buffer-full reason. See "METRICS" for more details on this and other reported metrics.

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.

on_start

$processor->on_start( $span, $parent_context );

Called when a span is started. In this class, this method does nothing.

on_end

$processor->on_end( $span );

Called when a span is ended, with the span that has just ended as its only parameter. This should be called after the span has been ended.

This method internally passes the span to "process", described in more detail below.

process

$processor->process( @spans );

Takes a list of spans that are ready for processing. Once called, this method will convert them into a readable instances and queue them for eventual exporting. Once enough spans have been queued, a batch of them will be sent to the configured exporter.

This processor batches spans for eventual processing, which can sometimes make for more complicated debugging. For a simpler processor that handles each span as it becomes ready and blocks during the export step, see OpenTelemetry::SDK::Trace::Processor::Simple.

force_flush

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

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

Takes an optional timeout in seconds. If this has been set, any spans remaining after the time has run out will be dropped and the number of dropped spans will be reported to the otel.bsp.spans.dropped metric with the force-flush reason. See "METRICS" for more details on this and other reported metrics.

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. Calls to "on_end" and "on_start" will immediately return and do nothing.

METRICS

This processor generates a number of metrics to keep track of its regular operation. At the time of writing, these metrics are non-standard, but their inclusion in the standard is being discussed.

otel.bsp.buffer.utilization

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

otel.bsp.failure

Incremented every time the span processing failed irrecoverably.

otel.bsp.spans.dropped

The number of spans that have been dropped and not successfully exported. This could be because they were never set to the exporter, of because the exporter reported some error.

Reported with the following attributes:

reason

buffer-full

The internal queue is full and can receive no more spans.

export-failure

The exporter reported an error while exporting the spans.

force-flush

The internal queue was flushed and not all queued spans could be exported in the specified time.

terminating

The processor was shutdown and some spans remained in its internal queue.

otel.bsp.spans.processed

The number of spans successfully processed.

otel.bsp.success

Incremented every time the span processing completed successfully.

SEE ALSO

Future

IO::Async

OpenTelemetry::Exporter

OpenTelemetry::SDK::Trace::Span::Readable

OpenTelemetry::Trace::Span

OpenTelemetry::Trace::Span::Processor

OpenTelemetry::Trace::Span::Processor::Simple

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 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.

cpanm OpenTelemetry::SDK

perl -MCPAN -e shell
install OpenTelemetry::SDK