feat(tracing): add init_default_subscriber_with_writer()

Author: jlizen

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

@@ -14,12 +14,16 @@ pub use tracing::*;
 
 /// Re-export the `tracing-subscriber` crate to build your own subscribers.
 pub use tracing_subscriber as subscriber;
+use tracing_subscriber::fmt::MakeWriter;
 
 const DEFAULT_LOG_LEVEL: &str = "INFO";
 
 /// Initialize `tracing-subscriber` with default logging options.
 ///
-/// This function uses environment variables set with [Lambda's advance logging controls](https://aws.amazon.com/blogs/compute/introducing-advanced-logging-controls-for-aws-lambda-functions/)
+/// The default subscriber writes logs to STDOUT in the current context.
+/// If you want to customize the writer, see [`init_default_subscriber_with_writer()`].
+///
+/// This function uses environment variables set with [Lambda's advanced logging controls](https://aws.amazon.com/blogs/compute/introducing-advanced-logging-controls-for-aws-lambda-functions/)
 /// if they're configured for your function.
 ///
 /// This subscriber sets the logging level based on environment variables:
@@ -31,6 +35,32 @@ const DEFAULT_LOG_LEVEL: &str = "INFO";
 /// If the `AWS_LAMBDA_LOG_FORMAT` environment variable is set to `JSON`, the log lines will be formatted as json objects,
 /// otherwise they will be formatted with the default tracing format.
 pub fn init_default_subscriber() {
+    init_default_subscriber_with_writer(std::io::stdout);
+}
+
+/// Initialize `tracing-subscriber` with default logging options, and a custom writer.
+///
+/// You might want to avoid writing to STDOUT in the local context via [`init_default_subscriber()`], if you have a high-throughput Lambdas that involve
+/// a lot of async concurrency. Since, writing to STDOUT can briefly block your tokio runtime - ref [tracing #2653](https://github.com/tokio-rs/tracing/issues/2653).
+/// In that case, you might prefer to use [tracing_appender::NonBlocking] instead - particularly if your Lambda is fairly long-running and stays warm.
+/// Though, note that you are then responsible
+/// for ensuring gracefuls shutdown. See [`examples/graceful-shutdown`] for a complete example.
+///
+/// This function uses environment variables set with [Lambda's advanced logging controls](https://aws.amazon.com/blogs/compute/introducing-advanced-logging-controls-for-aws-lambda-functions/)
+/// if they're configured for your function.
+///
+/// This subscriber sets the logging level based on environment variables:
+///     - if `AWS_LAMBDA_LOG_LEVEL` is set, it takes precedence over any other environment variables.
+///     - if `AWS_LAMBDA_LOG_LEVEL` is not set, check if `RUST_LOG` is set.
+///     - if none of those two variables are set, use `INFO` as the logging level.
+///
+/// The logging format can also be changed based on Lambda's advanced logging controls.
+/// If the `AWS_LAMBDA_LOG_FORMAT` environment variable is set to `JSON`, the log lines will be formatted as json objects,
+/// otherwise they will be formatted with the default tracing format.
+pub fn init_default_subscriber_with_writer<Writer>(writer: Writer)
+where
+    Writer: for<'writer> MakeWriter<'writer> + Send + Sync + 'static,
+{
     let log_format = env::var("AWS_LAMBDA_LOG_FORMAT").unwrap_or_default();
     let log_level_str = env::var("AWS_LAMBDA_LOG_LEVEL").or_else(|_| env::var("RUST_LOG"));
     let log_level =
@@ -43,7 +73,8 @@ pub fn init_default_subscriber() {
             EnvFilter::builder()
                 .with_default_directive(log_level.into())
                 .from_env_lossy(),
-        );
+        )
+        .with_writer(writer);
 
     if log_format.eq_ignore_ascii_case("json") {
         collector.json().init()