opentelemetry_lambda_tower/
lib.rs

1//! OpenTelemetry Tower middleware for AWS Lambda.
2//!
3//! This crate provides a Tower middleware layer that automatically instruments
4//! AWS Lambda handlers with OpenTelemetry tracing. It extracts trace context
5//! from various event sources (HTTP, SQS, SNS, etc.), creates properly
6//! attributed spans following OpenTelemetry semantic conventions, and handles
7//! span lifecycle management including flushing before Lambda freezes.
8//!
9//! # Architecture
10//!
11//! The middleware uses the `tracing` crate as its primary API, with
12//! `tracing-opentelemetry` bridging to OpenTelemetry for export. This allows
13//! natural use of `tracing` macros (`info!`, `debug!`, etc.) throughout your
14//! handler code.
15//!
16//! # Usage
17//!
18//! ```no_run
19//! use lambda_runtime::{run, service_fn, LambdaEvent, Error};
20//! use opentelemetry_lambda_tower::{OtelTracingLayer, HttpEventExtractor};
21//! use aws_lambda_events::apigw::ApiGatewayV2httpRequest;
22//! use tower::ServiceBuilder;
23//!
24//! async fn handler(
25//!     event: LambdaEvent<ApiGatewayV2httpRequest>,
26//! ) -> Result<serde_json::Value, Error> {
27//!     // Your handler logic - spans are automatically created
28//!     tracing::info!("Processing request");
29//!     Ok(serde_json::json!({"statusCode": 200}))
30//! }
31//!
32//! #[tokio::main]
33//! async fn main() -> Result<(), Error> {
34//!     // Initialise your tracer provider and set up tracing-opentelemetry subscriber
35//!     // ...
36//!
37//!     let tracing_layer = OtelTracingLayer::new(HttpEventExtractor::new());
38//!
39//!     let service = ServiceBuilder::new()
40//!         .layer(tracing_layer)
41//!         .service(service_fn(handler));
42//!
43//!     run(service).await
44//! }
45//! ```
46//!
47//! # Trace Context Extraction
48//!
49//! Different event sources carry trace context in different locations:
50//!
51//! - **HTTP (API Gateway)**: `traceparent` header using W3C Trace Context
52//! - **SQS**: `AWSTraceHeader` in message system attributes (creates span links)
53//! - **SNS**: Similar to SQS
54//!
55//! The middleware automatically detects and extracts context appropriately.
56//!
57//! # Features
58//!
59//! - `http` - API Gateway v1/v2 extractor (enabled by default)
60//! - `sqs` - SQS event extractor (enabled by default)
61//! - `sns` - SNS event extractor
62//! - `lambda-http` - Integration with the `lambda_http` crate
63//! - `full` - All extractors
64
65mod cold_start;
66mod extractor;
67mod future;
68mod layer;
69mod service;
70
71pub mod extractors;
72
73pub use cold_start::check_cold_start;
74pub use extractor::TraceContextExtractor;
75pub use future::OtelTracingFuture;
76pub use layer::{OtelTracingLayer, OtelTracingLayerBuilder};
77pub use service::OtelTracingService;
78
79// Re-export commonly used extractors at crate root
80#[cfg(feature = "http")]
81pub use extractors::http::{ApiGatewayV1Extractor, ApiGatewayV2Extractor, HttpEventExtractor};
82
83#[cfg(feature = "sqs")]
84pub use extractors::sqs::SqsEventExtractor;
85
86#[cfg(feature = "sns")]
87pub use extractors::sns::SnsEventExtractor;
88
89#[cfg(feature = "lambda-http")]
90pub use extractors::lambda_http::LambdaHttpExtractor;
opentelemetry_lambda_tower/lib.rs

opentelemetry_lambda_tower/
lib.rs
