Module handler

Lambda function handler wrapper with OpenTelemetry tracing.

This module provides a wrapper function that automatically creates OpenTelemetry spans for Lambda function invocations. It offers an alternative to the Tower middleware layer when more direct control over span creation is needed.

When to Use the Handler Wrapper

The handler wrapper approach is recommended when:

• You have a simple Lambda function without complex middleware needs
• You want minimal setup and configuration
• You need direct control over span creation and attributes
• You don’t need Tower’s middleware composition features

For more complex applications, consider using the Tower layer approach instead.

Features

• Automatic span creation with configurable names and attributes
• Built-in support for common AWS event types (API Gateway v1/v2)
• Automatic context propagation from HTTP headers
• Response status code tracking
• Custom attribute extraction

Architecture

The handler wrapper operates by:

1. Creating a span for each invocation
2. Extracting attributes from the event
3. Running the handler function within the span
4. Capturing response attributes (e.g., status code)
5. Signaling completion for span export

Performance Considerations

The wrapper is designed to minimize overhead:

• Lazy attribute extraction
• Efficient downcasting for type detection
• Minimal allocations for span attributes
• No blocking operations in the critical path

Comparison with Tower Layer

This wrapper provides an alternative to the OtelTracingLayer:

• More direct control over span creation
• Simpler integration (no middleware stack)
• Easier to customize span attributes
• Better suited for simple Lambda functions

Use this wrapper when:

• You have a simple Lambda function
• You don’t need other Tower middleware
• You want direct control over spans

Use the Tower layer when:

• You’re building a complex service
• You need other Tower middleware
• You want standardized instrumentation

Examples

Functions

create_traced_handler

Creates a traced handler function that can be used directly with service_fn.

Type Aliases

TracedHandler

Type representing a traced Lambda handler function. Takes a LambdaEvent<T> and returns a Future that resolves to Result<R, Error>.