Trait SpanAttributesExtractor

pub trait SpanAttributesExtractor {
    // Required method
    fn extract_span_attributes(&self) -> SpanAttributes;
}

Trait for types that can provide span attributes.

This trait enables automatic extraction of OpenTelemetry span attributes from event types. The tracing layer automatically detects and uses implementations of this trait when processing Lambda events.

Implementation Guidelines

When implementing this trait, follow these best practices:

1. Attribute Naming:

   • Follow OpenTelemetry semantic conventions
   • Use lowercase with dots for namespacing (e.g., “http.method”)
   • Keep names concise but descriptive

2. Span Kind:

   • Set appropriate kind based on event type:
     • “SERVER” for inbound requests (default)
     • “CONSUMER” for event/message processing
     • “CLIENT” for outbound calls

3. Context Propagation:

   • Extract both W3C Trace Context and AWS X-Ray headers
   • Handle traceparent, tracestate, and x-amzn-trace-id headers
   • Validate header values when possible

4. Performance:

   • Minimize string allocations
   • Avoid unnecessary cloning
   • Filter out invalid or unnecessary headers

Examples

Basic implementation for a custom event:

use lambda_otel_lite::{SpanAttributes, SpanAttributesExtractor};
use std::collections::HashMap;
use opentelemetry::Value;

struct CustomEvent {
    operation: String,
    trace_parent: Option<String>,
}

impl SpanAttributesExtractor for CustomEvent {
    fn extract_span_attributes(&self) -> SpanAttributes {
        let mut attributes = HashMap::new();
        attributes.insert("operation".to_string(), Value::String(self.operation.clone().into()));

        // Add trace context if available
        let mut carrier = HashMap::new();
        if let Some(header) = &self.trace_parent {
            carrier.insert("traceparent".to_string(), header.clone());
        }
        // You can also handle X-Ray headers
        // if let Some(xray_header) = &self.xray_trace_id {
        //    carrier.insert("x-amzn-trace-id".to_string(), xray_header.clone());
        // }

        SpanAttributes::builder()
            .attributes(attributes)
            .carrier(carrier)
            .build()
    }
}

Required Methods

fn extract_span_attributes(&self) -> SpanAttributes

Extract span attributes from this type.

This method should extract any relevant information from the implementing type that should be included in the OpenTelemetry span. This includes:

• Custom attributes describing the event
• Span kind if different from SERVER
• Headers for context propagation
• Links to related traces

Returns

Returns a SpanAttributes instance containing all extracted information. If extraction fails in any way, it should return a default instance rather than failing.

Implementations on Foreign Types

impl SpanAttributesExtractor for Value

Default implementation for serde_json::Value.

This implementation provides a fallback for when the event type is not known or when working with raw JSON data. It returns default attributes with the trigger type set to “other”. If there’s a headers field, it will be used to populate the carrier.

fn extract_span_attributes(&self) -> SpanAttributes

impl SpanAttributesExtractor for AlbTargetGroupRequest

Implementation for Application Load Balancer target group events.

Extracts standard HTTP attributes following OpenTelemetry semantic conventions:

• http.request.method: The HTTP method
• url.path: The request path
• url.query: The query string (constructed from multi_value_query_string_parameters)
• url.scheme: The protocol scheme (defaults to “http”)
• network.protocol.version: The HTTP protocol version (always “1.1” for ALB)
• http.route: The request path
• client.address: The client’s IP address (from x-forwarded-for header)
• user_agent.original: The user agent header
• server.address: The host header
• alb.target_group_arn: The ARN of the target group

Also extracts W3C Trace Context headers and AWS X-Ray headers for distributed tracing.

fn extract_span_attributes(&self) -> SpanAttributes

impl SpanAttributesExtractor for ApiGatewayProxyRequest

Implementation for API Gateway V1 REST API events.

Extracts standard HTTP attributes following OpenTelemetry semantic conventions:

• http.request.method: The HTTP method
• url.path: The request path
• url.query: The query string (constructed from multi_value_query_string_parameters)
• url.scheme: The protocol scheme (always “https” for API Gateway)
• network.protocol.version: The HTTP protocol version
• http.route: The API Gateway resource path
• client.address: The client’s IP address (from identity.source_ip)
• user_agent.original: The user agent header
• server.address: The domain name

Also extracts W3C Trace Context headers and AWS X-Ray headers for distributed tracing.

fn extract_span_attributes(&self) -> SpanAttributes

impl SpanAttributesExtractor for ApiGatewayV2httpRequest

Implementation for API Gateway V2 HTTP API events.

Extracts standard HTTP attributes following OpenTelemetry semantic conventions:

• http.request.method: The HTTP method
• url.path: The request path (from raw_path)
• url.query: The query string if present (from raw_query_string)
• url.scheme: The protocol scheme (always “https” for API Gateway)
• network.protocol.version: The HTTP protocol version
• http.route: The API Gateway route key (e.g. “$default” or “GET /users/{id}”)
• client.address: The client’s IP address (from source_ip)
• user_agent.original: The user agent header
• server.address: The domain name

Also extracts W3C Trace Context headers and AWS X-Ray headers for distributed tracing.

fn extract_span_attributes(&self) -> SpanAttributes

Implementors