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

Basic usage with JSON events:

use lambda_otel_lite::{init_telemetry, traced_handler, TelemetryConfig};
use lambda_runtime::{service_fn, Error, LambdaEvent, Runtime};
use aws_lambda_events::event::apigw::ApiGatewayV2httpRequest;

async fn function_handler(event: LambdaEvent<ApiGatewayV2httpRequest>) -> Result<serde_json::Value, Error> {
    Ok(serde_json::json!({
        "statusCode": 200,
        "body": format!("Hello from request {}", event.context.request_id)
    }))
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    let completion_handler = init_telemetry(TelemetryConfig::default()).await?;
     
    let runtime = Runtime::new(service_fn(|event| {
        traced_handler("my-handler", event, completion_handler.clone(), function_handler)
    }));

    runtime.run().await
}

Using with API Gateway events:

use lambda_otel_lite::{init_telemetry, traced_handler, TelemetryConfig};
use lambda_runtime::{service_fn, Error, LambdaEvent, Runtime};
use aws_lambda_events::event::apigw::ApiGatewayV2httpRequest;

async fn api_handler(
    event: LambdaEvent<ApiGatewayV2httpRequest>
) -> Result<serde_json::Value, Error> {
    // HTTP attributes will be automatically extracted
    Ok(serde_json::json!({
        "statusCode": 200,
        "body": format!("Hello from request {}", event.context.request_id)
    }))
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    let completion_handler = init_telemetry(TelemetryConfig::default()).await?;
     
    let runtime = Runtime::new(service_fn(|event| {
        traced_handler("api-handler", event, completion_handler.clone(), api_handler)
    }));

    runtime.run().await
}

Functions

traced_handler

Wraps a Lambda handler function with OpenTelemetry tracing.