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//! - `full` - All extractors
63
64mod cold_start;
65mod extractor;
66mod future;
67mod layer;
68mod service;
69
70pub mod extractors;
71
72pub use cold_start::check_cold_start;
73pub use extractor::TraceContextExtractor;
74pub use future::OtelTracingFuture;
75pub use layer::{OtelTracingLayer, OtelTracingLayerBuilder};
76pub use service::OtelTracingService;
77
78// Re-export commonly used extractors at crate root
79#[cfg(feature = "http")]
80pub use extractors::http::{ApiGatewayV1Extractor, ApiGatewayV2Extractor, HttpEventExtractor};
81
82#[cfg(feature = "sqs")]
83pub use extractors::sqs::SqsEventExtractor;
84
85#[cfg(feature = "sns")]
86pub use extractors::sns::SnsEventExtractor;
opentelemetry_lambda_tower/lib.rs

opentelemetry_lambda_tower/
lib.rs
