Module extractors

Attribute extraction for OpenTelemetry spans in AWS Lambda functions.

This module provides functionality for extracting OpenTelemetry span attributes from AWS Lambda events. It includes:

• Built-in support for common AWS event types (API Gateway, ALB)
• Extensible trait system for custom event types
• Automatic W3C Trace Context and AWS X-Ray propagation
• Support for span links and custom attributes

Architecture

The module uses a trait-based approach for attribute extraction:

1. Event Processing: Each supported event type implements the SpanAttributesExtractor trait
2. Attribute Collection: Standard attributes are collected based on event type
3. Context Propagation: W3C Trace Context and AWS X-Ray headers are automatically extracted
4. Custom Attributes: Additional attributes can be added through custom implementations

Automatic Attributes

The module automatically extracts and sets several types of attributes:

Resource Attributes

• cloud.provider: Set to “aws”
• cloud.region: From AWS_REGION
• faas.name: From AWS_LAMBDA_FUNCTION_NAME
• faas.version: From AWS_LAMBDA_FUNCTION_VERSION
• faas.instance: From AWS_LAMBDA_LOG_STREAM_NAME
• faas.max_memory: From AWS_LAMBDA_FUNCTION_MEMORY_SIZE
• service.name: From OTEL_SERVICE_NAME or function name

Span Attributes

• faas.coldstart: True only on first invocation
• faas.invocation_id: From Lambda request ID
• cloud.account.id: From function ARN
• cloud.resource_id: Complete function ARN
• otel.kind: “SERVER” by default
• otel.status_code/message: From response processing

HTTP Attributes (for supported event types)

• faas.trigger: Set to “http” for API/ALB events
• http.status_code: From response
• http.route: Route key or resource path
• http.method: HTTP method
• url.path: Request path
• url.query: Query parameters if present
• url.scheme: Protocol (https)
• network.protocol.version: HTTP version
• client.address: Client IP address
• user_agent.original: User agent string
• server.address: Server hostname

Built-in Support

The following AWS event types are supported out of the box:

• API Gateway v1/v2 (HTTP API and REST API)
• Application Load Balancer

Each implementation follows OpenTelemetry semantic conventions for HTTP spans:

• http.request.method: The HTTP method (e.g., “GET”, “POST”)
• url.path: The request path
• url.query: The query string (if present)
• url.scheme: The protocol scheme (“https” for API Gateway, configurable for ALB)
• network.protocol.version: The HTTP protocol version
• http.route: The route pattern or resource path
• client.address: The client’s IP address
• user_agent.original: The user agent string
• server.address: The server’s domain name or host

Performance Considerations

• Attribute extraction is done lazily when spans are created
• String allocations are minimized where possible
• Header extraction filters invalid UTF-8 values

Structs

SpanAttributes

Data extracted from a Lambda event for span creation.

SpanAttributesBuilder

Use builder syntax to set the inputs and finish with build().

Enums

TriggerType

Common trigger types for Lambda functions.

Traits

SpanAttributesExtractor

Trait for types that can provide span attributes.

Functions

get_status_code

Extract status code from response if it’s an HTTP response.

set_common_attributes

Set common attributes on the span based on the Lambda context.

set_response_attributes

Set response attributes on the span based on the response value.