Implement Lambda's advance logging controls.

Provide a feature that exposes a initialization function for `tracing-subscriber` that sets the right logging controls based on Lambda's configuration.
The feature is enabled by default, but it can be disabled if a user doesn't want to use it.

Signed-off-by: David Calavera <[email protected]>

Author: calavera

README.md

@@ -372,6 +372,24 @@ You can read more about how [cargo lambda watch](https://www.cargo-lambda.info/c
 
 Lambdas can be run and debugged locally using a special [Lambda debug proxy](https://github.com/rimutaka/lambda-debug-proxy) (a non-AWS repo maintained by @rimutaka), which is a Lambda function that forwards incoming requests to one AWS SQS queue and reads responses from another queue. A local proxy running on your development computer reads the queue, calls your Lambda locally and sends back the response. This approach allows debugging of Lambda functions locally while being part of your AWS workflow. The Lambda handler code does not need to be modified between the local and AWS versions.
 
+## Tracing and Logging
+
+The Rust Runtime for Lambda integrates with the (Tracing)[https://tracing.rs] libraries to provide tracing and logging.
+
+By default, the runtime emits `tracing` events that you can collect via `tracing-subscriber`. It also enabled a feature called `tracing` that exposes a default subsriber with sensible options to send logging information to AWS CloudWatch. Follow the next example that shows how to enable the default subscriber:
+
+```rust
+use lambda_runtime::{run, service_fn, tracing, Error};
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing::init_default_subscriber();
+    run(service_fn(|event| tracing::info!(?event))).await
+}
+```
+
+The subscriber uses `RUST_LOG` as the environment variable to determine the log level for your function. It also uses [Lambda's advance logging controls](https://aws.amazon.com/blogs/compute/introducing-advanced-logging-controls-for-aws-lambda-functions/) if they're configured for your function. By default, the log level to emit events is `INFO`.
+
 ## AWS event objects
 
 This project includes Lambda event struct definitions, [`aws_lambda_events`](https://crates.io/crates/aws_lambda_events). This crate can be leveraged to provide strongly-typed Lambda event structs. You can create your own custom event objects and their corresponding structs as well.

lambda-extension/Cargo.toml

@@ -13,6 +13,10 @@ categories = ["web-programming::http-server"]
 keywords = ["AWS", "Lambda", "API"]
 readme = "README.md"
 
+[features]
+default = ["tracing"]
+tracing = ["lambda_runtime_api_client/tracing"]
+
 [dependencies]
 async-stream = "0.3"
 bytes = { workspace = true }
@@ -24,7 +28,6 @@ hyper-util = { workspace = true }
 lambda_runtime_api_client = { version = "0.9", path = "../lambda-runtime-api-client" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "^1"
-tracing = { version = "0.1", features = ["log"] }
 tokio = { version = "1.0", features = [
     "macros",
     "io-util",
@@ -33,3 +36,4 @@ tokio = { version = "1.0", features = [
 ] }
 tokio-stream = "0.1.2"
 tower = { version = "0.4", features = ["make", "util"] }
+tracing = { version = "0.1", features = ["log"] }

lambda-extension/src/lib.rs

@@ -23,6 +23,10 @@ pub use telemetry::*;
 /// Include several request builders to interact with the Extension API.
 pub mod requests;
 
+/// Utilities to initialize and use `tracing` and `tracing-subscriber` in Lambda Functions.
+#[cfg(feature = "tracing")]
+pub use lambda_runtime_api_client::tracing;
+
 /// Execute the given events processor
 pub async fn run<E>(events_processor: E) -> Result<(), Error>
 where

lambda-http/Cargo.toml

@@ -16,12 +16,13 @@ categories = ["web-programming::http-server"]
 readme = "README.md"
 
 [features]
-default = ["apigw_rest", "apigw_http", "apigw_websockets", "alb"]
+default = ["apigw_rest", "apigw_http", "apigw_websockets", "alb", "tracing"]
 apigw_rest = []
 apigw_http = []
 apigw_websockets = []
 alb = []
 pass_through = []
+tracing = ["lambda_runtime/tracing"]
 
 [dependencies]
 base64 = { workspace = true }

lambda-http/src/lib.rs

@@ -65,8 +65,10 @@
 extern crate maplit;
 
 pub use http::{self, Response};
-use lambda_runtime::LambdaEvent;
-pub use lambda_runtime::{self, service_fn, tower, Context, Error, Service};
+/// Utilities to initialize and use `tracing` and `tracing-subscriber` in Lambda Functions.
+#[cfg(feature = "tracing")]
+pub use lambda_runtime::tracing;
+pub use lambda_runtime::{self, service_fn, tower, Context, Error, LambdaEvent, Service};
 use request::RequestFuture;
 use response::ResponseFuture;
 

lambda-runtime-api-client/Cargo.toml

@@ -13,6 +13,10 @@ categories = ["web-programming::http-server"]
 keywords = ["AWS", "Lambda", "API"]
 readme = "README.md"
 
+[features]
+default = ["tracing"]
+tracing = ["dep:tracing-subscriber"]
+
 [dependencies]
 bytes = { workspace = true }
 futures-channel = { workspace = true }
@@ -30,3 +34,5 @@ hyper-util = { workspace = true, features = [
 tower = { workspace = true, features = ["util"] }
 tower-service = { workspace = true }
 tokio = { version = "1.0", features = ["io-util"] }
+tracing = { version = "0.1", features = ["log"] }
+tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "json", "env-filter"], optional = true }

lambda-runtime-api-client/src/lib.rs

@@ -17,6 +17,11 @@ mod error;
 pub use error::*;
 pub mod body;
 
+use tracing::trace;
+
+#[cfg(feature = "tracing")]
+pub mod tracing;
+
 /// API client to interact with the AWS Lambda Runtime API.
 #[derive(Debug)]
 pub struct Client {
@@ -40,8 +45,10 @@ impl Client {
     /// Send a given request to the Runtime API.
     /// Use the client's base URI to ensure the API endpoint is correct.
     pub async fn call(&self, req: Request<body::Body>) -> Result<Response<Incoming>, BoxError> {
-        let req = self.set_origin(req)?;
-        self.client.request(req).await.map_err(Into::into)
+        let request = self.set_origin(req)?;
+
+        trace!(?request, "sending request to Lambda Runtime API");
+        self.client.request(request).await.map_err(Into::into)
     }
 
     /// Create a new client with a given base URI and HTTP connector.
@@ -70,6 +77,8 @@ impl Client {
             .build()
             .map_err(Box::new)?;
 
+        trace!(?uri, "setting the Lambda Runtime API origin URI");
+
         parts.uri = uri;
         Ok(Request::from_parts(parts, body))
     }

lambda-runtime-api-client/src/tracing.rs

@@ -0,0 +1,41 @@
+//! This module provides primitives to work with `tracing`
+//! and `tracing-subscriber` in Lambda functions.
+//!
+//! The `tracing` and `tracing-subscriber` crates are re-exported
+//! so you don't have to include them as direct dependencies in
+//! your projects.
+
+use std::{env, str::FromStr};
+
+use subscriber::filter::{EnvFilter, LevelFilter};
+/// Re-export the `tracing` crate to have access to tracing macros
+/// like `info!`, `debug!`, `trace!` and so on.
+pub use tracing::*;
+
+/// Re-export the `tracing-subscriber` crate to build your own subscribers.
+pub use tracing_subscriber as subscriber;
+
+/// Initialize `tracing-subscriber` with default options.
+/// The subscriber uses `RUST_LOG` as the environment variable to determine the log level for your function.
+/// It also uses [Lambda's advance logging controls](https://aws.amazon.com/blogs/compute/introducing-advanced-logging-controls-for-aws-lambda-functions/)
+/// if they're configured for your function.
+/// By default, the log level to emit events is `INFO`.
+pub fn init_default_subscriber() {
+    let log_format = env::var("AWS_LAMBDA_LOG_FORMAT").unwrap_or_default();
+    let log_level = Level::from_str(&env::var("AWS_LAMBDA_LOG_LEVEL").unwrap_or_default()).unwrap_or(Level::INFO);
+
+    let collector = tracing_subscriber::fmt()
+        .with_target(false)
+        .without_time()
+        .with_env_filter(
+            EnvFilter::builder()
+                .with_default_directive(LevelFilter::from_level(log_level).into())
+                .from_env_lossy(),
+        );
+
+    if log_format.eq_ignore_ascii_case("json") {
+        collector.json().init()
+    } else {
+        collector.init()
+    }
+}

lambda-runtime/Cargo.toml

@@ -14,8 +14,8 @@ keywords = ["AWS", "Lambda", "API"]
 readme = "../README.md"
 
 [features]
-default = ["simulated"]
-simulated = []
+default = ["tracing"]
+tracing = ["lambda_runtime_api_client/tracing"]
 
 [dependencies]
 async-stream = "0.3"

lambda-runtime/src/lib.rs

@@ -30,6 +30,11 @@ mod deserializer;
 mod requests;
 /// Utilities for Lambda Streaming functions.
 pub mod streaming;
+
+/// Utilities to initialize and use `tracing` and `tracing-subscriber` in Lambda Functions.
+#[cfg(feature = "tracing")]
+pub use lambda_runtime_api_client::tracing;
+
 /// Types available to a Lambda function.
 mod types;