Module extension

Lambda Extension for OpenTelemetry span processing.

This module provides an internal Lambda extension that manages the lifecycle of OpenTelemetry spans. The extension integrates with AWS Lambda’s Extensions API to efficiently manage telemetry data collection and export.

Architecture

The extension operates as a background task within the Lambda function process and communicates with both the Lambda Runtime API and the function handler through asynchronous channels:

1. Extension Registration: On startup, the extension task registers with the Lambda Extensions API and subscribes to the appropriate events based on the processing mode.

2. Handler Communication: The extension uses a channel-based communication pattern to coordinate with the function handler for span export timing.

3. Processing Modes:

   • Async: Registers for INVOKE events and exports spans after handler completion
     • Spans are queued during handler execution
     • Export occurs after response is sent to user
     • Best for high-volume telemetry
   • Finalize: Registers with no events
     • Only installs SIGTERM handler
     • Lets application code control span export
     • Compatible with BatchSpanProcessor

4. Graceful Shutdown: The extension implements proper shutdown handling to ensure no telemetry data is lost when the Lambda environment is terminated.

Error Handling

The extension implements robust error handling:

• Logs all export errors without failing the function
• Implements graceful shutdown on SIGTERM
• Handles channel communication failures

Structs

OtelInternalExtension

Extension that flushes OpenTelemetry spans after each Lambda invocation.