Module processor

Span processor implementation optimized for AWS Lambda functions.

This module provides a Lambda-optimized span processor that efficiently manages OpenTelemetry spans in a serverless environment. It uses a ring buffer to store spans in memory and supports different processing modes to balance latency and reliability.

Processing Modes

The processor supports three modes for span export:

1. Sync Mode (default):

   • Direct, synchronous export in handler thread
   • Recommended for low-volume telemetry or when latency is not critical
   • Best for development and debugging
   • Set via LAMBDA_EXTENSION_SPAN_PROCESSOR_MODE=sync

2. Async Mode:

   • Export via Lambda extension using AWS Lambda Extensions API
   • Spans are queued and exported after handler completion
   • Uses channel-based communication between handler and extension
   • Best for production use with high telemetry volume
   • Set via LAMBDA_EXTENSION_SPAN_PROCESSOR_MODE=async

3. Finalize Mode:

   • Only registers extension with no events
   • Ensures SIGTERM handler for graceful shutdown
   • Compatible with BatchSpanProcessor for custom export strategies
   • Best for specialized export requirements
   • Set via LAMBDA_EXTENSION_SPAN_PROCESSOR_MODE=finalize

Architecture

The processor is designed specifically for the Lambda execution environment:

1. Ring Buffer Storage:

   • Fixed-size circular buffer prevents memory growth
   • O(1) push operations with no memory reallocation
   • FIFO ordering ensures spans are processed in order
   • Efficient batch removal for export
   • When full, new spans are dropped (with warning logs)

2. Thread Safety:

   • All operations are thread-safe
   • Uses Mutex for span buffer access
   • Atomic operations for state management
   • Safe for concurrent span submission

Configuration

The processor can be configured through environment variables:

• LAMBDA_EXTENSION_SPAN_PROCESSOR_MODE: Controls processing mode

  • “sync” for Sync mode (default)
  • “async” for Async mode
  • “finalize” for Finalize mode

• LAMBDA_SPAN_PROCESSOR_QUEUE_SIZE: Controls buffer size

  • Defaults to 2048 spans
  • Should be tuned based on span volume

Usage Examples

Basic setup with default configuration:

use lambda_otel_lite::{ProcessorConfig, LambdaSpanProcessor};
use otlp_stdout_span_exporter::OtlpStdoutSpanExporter;

let processor = LambdaSpanProcessor::new(
    Box::new(OtlpStdoutSpanExporter::default()),
    ProcessorConfig::default()
);

Custom configuration for high-volume scenarios:

use lambda_otel_lite::{ProcessorConfig, LambdaSpanProcessor};
use otlp_stdout_span_exporter::OtlpStdoutSpanExporter;

let processor = LambdaSpanProcessor::new(
    Box::new(OtlpStdoutSpanExporter::default()),
    ProcessorConfig {
        max_queue_size: 4096, // Larger buffer for high volume
    }
);

Performance Considerations

1. Memory Usage:

   • Fixed memory footprint based on queue size
   • Each span typically uses 100-500 bytes
   • Default 2048 spans ≈ 0.5-1MB memory

2. Latency Impact:

   • Sync mode: Adds export time to handler latency
   • Async mode: Minimal impact (just span queueing)
   • Finalize mode: Depends on processor implementation

3. Reliability:

   • Spans may be dropped if buffer fills
   • Warning logs indicate dropped spans
   • Consider increasing buffer size if spans are dropped

Best Practices

1. Mode Selection:

   • Consider payload size and memory/CPU configuration
   • Use Sync mode for simple exports or low resource environments
   • Use Async mode the telemetrry payload is expected to be large, and the extension overhead is an acceptable trade-off with the handler latency
   • Use Finalize mode for custom export strategies

2. Buffer Sizing:

   • Monitor dropped_spans metric
   • Size based on max spans per invocation
   • Consider function memory when sizing

3. Error Handling:

   • Export errors are logged but don’t fail function
   • Monitor for export failures in logs
   • Consider retry strategies in custom exporters

Structs

LambdaSpanProcessor

Lambda-optimized span processor implementation.

ProcessorConfig

Configuration for the Lambda span processor.

Enums

ProcessorMode

Controls how spans are processed and exported.