[add] builder api for creating loggers.

Author: vmarcella

crates/lambda-rs-logging/README.md

@@ -51,8 +51,11 @@ fn main() {
 use lambda_rs_logging as logging;
 
 fn main() {
-  let logger = logging::Logger::new(logging::LogLevel::INFO, "my-app");
-  logger.add_handler(Box::new(logging::handler::ConsoleHandler::new("my-app")));
+  let logger = logging::Logger::builder()
+      .name("my-app")
+      .level(logging::LogLevel::INFO)
+      .with_handler(Box::new(logging::handler::ConsoleHandler::new("my-app")))
+      .build();
 
   logger.info("Hello world".to_string());
   logger.warn("Be careful".to_string());
@@ -64,8 +67,11 @@ fn main() {
 use lambda_rs_logging as logging;
 
 fn main() {
-  let logger = logging::Logger::new(logging::LogLevel::DEBUG, "app");
-  logger.add_handler(Box::new(logging::handler::ConsoleHandler::new("app")));
+  let logger = logging::Logger::builder()
+      .name("app")
+      .level(logging::LogLevel::DEBUG)
+      .with_handler(Box::new(logging::handler::ConsoleHandler::new("app")))
+      .build();
 
   // Set the global logger before any macros are used
   logging::Logger::init(logger).expect("global logger can only be initialized once");
@@ -74,10 +80,24 @@ fn main() {
 }
 ```
 
+### Configure level from environment
+```rust
+use lambda_rs_logging as logging;
+
+fn main() {
+  // LAMBDA_LOG can be: trace|debug|info|warn|error|fatal
+  // Example: export LAMBDA_LOG=debug
+  logging::env::init_global_from_env().ok();
+
+  logging::info!("respects env filter");
+}
+```
+
 ## Notes
 - Thread-safe global with `OnceLock<Arc<Logger>>`.
 - Handlers are `Send + Sync` and receive a `Record` internally (phase 1 refactor).
 - `fatal!` logs at FATAL level but does not exit the process. Prefer explicit exits in your app logic.
+- Console handler colors only when attached to a TTY and writes WARN+ to stderr.
 
 ## Examples
 This crate ships with examples. From the repository root:
@@ -86,3 +106,8 @@ cargo run -p lambda-rs-logging --example 01_global_macros
 cargo run -p lambda-rs-logging --example 02_custom_logger
 cargo run -p lambda-rs-logging --example 03_global_init
 ```
+
+### Environment example
+```bash
+LAMBDA_LOG=debug cargo run -p lambda-rs-logging --example 01_global_macros
+```

crates/lambda-rs-logging/examples/04_builder_env.rs

@@ -0,0 +1,19 @@
+// When building examples inside the crate, the library is available as `logging`.
+// If you copy this example to another crate, import with `use lambda_rs_logging as logging;`
+use logging;
+
+fn main() {
+  // Build a custom logger and apply env level
+  let logger = logging::Logger::builder()
+    .name("builder-env")
+    .level(logging::LogLevel::INFO)
+    .with_handler(Box::new(logging::handler::ConsoleHandler::new(
+      "builder-env",
+    )))
+    .build();
+
+  logging::env::apply_env_level(&logger, Some("LAMBDA_LOG"));
+
+  logger.debug("filtered unless LAMBDA_LOG=debug".to_string());
+  logger.info("visible at info".to_string());
+}

crates/lambda-rs-logging/src/handler.rs

@@ -2,7 +2,11 @@
 
 use std::{
   fs::OpenOptions,
-  io::Write,
+  io::{
+    self,
+    IsTerminal,
+    Write,
+  },
   sync::Mutex,
   time::SystemTime,
 };
@@ -105,15 +109,45 @@ impl Handler for ConsoleHandler {
       timestamp, record.level, self.name, record.message
     );
 
-    let colored_message = match record.level {
-      LogLevel::TRACE => format!("\x1B[37m{}\x1B[0m", log_message),
-      LogLevel::DEBUG => format!("\x1B[35m{}\x1B[0m", log_message),
-      LogLevel::INFO => format!("\x1B[32m{}\x1B[0m", log_message),
-      LogLevel::WARN => format!("\x1B[33m{}\x1B[0m", log_message),
-      LogLevel::ERROR => format!("\x1B[31;1m{}\x1B[0m", log_message),
-      LogLevel::FATAL => format!("\x1B[31;1m{}\x1B[0m", log_message),
-    };
-
-    println!("{}", colored_message);
+    // Select output stream based on level.
+    let warn_or_higher = matches!(
+      record.level,
+      LogLevel::WARN | LogLevel::ERROR | LogLevel::FATAL
+    );
+    if warn_or_higher {
+      let mut e = io::stderr().lock();
+      let use_color = io::stderr().is_terminal();
+      if use_color {
+        let colored = match record.level {
+          LogLevel::TRACE => format!("\x1B[37m{}\x1B[0m", log_message),
+          LogLevel::DEBUG => format!("\x1B[35m{}\x1B[0m", log_message),
+          LogLevel::INFO => format!("\x1B[32m{}\x1B[0m", log_message),
+          LogLevel::WARN => format!("\x1B[33m{}\x1B[0m", log_message),
+          LogLevel::ERROR | LogLevel::FATAL => {
+            format!("\x1B[31;1m{}\x1B[0m", log_message)
+          }
+        };
+        let _ = writeln!(e, "{}", colored);
+      } else {
+        let _ = writeln!(e, "{}", log_message);
+      }
+    } else {
+      let mut o = io::stdout().lock();
+      let use_color = io::stdout().is_terminal();
+      if use_color {
+        let colored = match record.level {
+          LogLevel::TRACE => format!("\x1B[37m{}\x1B[0m", log_message),
+          LogLevel::DEBUG => format!("\x1B[35m{}\x1B[0m", log_message),
+          LogLevel::INFO => format!("\x1B[32m{}\x1B[0m", log_message),
+          LogLevel::WARN => format!("\x1B[33m{}\x1B[0m", log_message),
+          LogLevel::ERROR | LogLevel::FATAL => {
+            format!("\x1B[31;1m{}\x1B[0m", log_message)
+          }
+        };
+        let _ = writeln!(o, "{}", colored);
+      } else {
+        let _ = writeln!(o, "{}", log_message);
+      }
+    }
   }
 }

crates/lambda-rs-logging/src/lib.rs

@@ -71,6 +71,11 @@ impl Logger {
     }
   }
 
+  /// Creates a builder for configuring a `Logger`.
+  pub fn builder() -> LoggerBuilder {
+    LoggerBuilder::default()
+  }
+
   /// Returns the global logger (thread-safe). Initializes with a default
   /// console handler if not explicitly initialized via `init`.
   pub fn global() -> &'static Arc<Self> {
@@ -176,6 +181,93 @@ impl Logger {
 pub enum InitError {
   AlreadyInitialized,
 }
+
+/// Logger builder for ergonomic configuration.
+pub struct LoggerBuilder {
+  name: String,
+  level: LogLevel,
+  handlers: Vec<Box<dyn handler::Handler>>,
+}
+
+impl Default for LoggerBuilder {
+  fn default() -> Self {
+    Self {
+      name: "lambda-rs".to_string(),
+      level: LogLevel::INFO,
+      handlers: Vec::new(),
+    }
+  }
+}
+
+impl LoggerBuilder {
+  pub fn name(mut self, name: &str) -> Self {
+    self.name = name.to_string();
+    self
+  }
+
+  pub fn level(mut self, level: LogLevel) -> Self {
+    self.level = level;
+    self
+  }
+
+  pub fn with_handler(mut self, handler: Box<dyn handler::Handler>) -> Self {
+    self.handlers.push(handler);
+    self
+  }
+
+  pub fn build(self) -> Logger {
+    let logger = Logger::new(self.level, &self.name);
+    for h in self.handlers {
+      logger.add_handler(h);
+    }
+    logger
+  }
+}
+
+/// Environment configuration helpers.
+pub mod env {
+  use super::{
+    LogLevel,
+    Logger,
+  };
+
+  /// Parse a log level from a string like "trace", "debug", ...
+  pub fn parse_level(s: &str) -> Option<LogLevel> {
+    match s.trim().to_ascii_lowercase().as_str() {
+      "trace" => Some(LogLevel::TRACE),
+      "debug" => Some(LogLevel::DEBUG),
+      "info" => Some(LogLevel::INFO),
+      "warn" | "warning" => Some(LogLevel::WARN),
+      "error" => Some(LogLevel::ERROR),
+      "fatal" => Some(LogLevel::FATAL),
+      _ => None,
+    }
+  }
+
+  /// Applies a level from the environment to the provided logger.
+  ///
+  /// Reads the specified `var` (default: "LAMBDA_LOG"). If it parses to a level,
+  /// updates the logger's level.
+  pub fn apply_env_level(logger: &Logger, var: Option<&str>) {
+    let key = var.unwrap_or("LAMBDA_LOG");
+    if let Ok(val) = std::env::var(key) {
+      if let Some(level) = parse_level(&val) {
+        logger.set_level(level);
+      }
+    }
+  }
+
+  /// Initialize a global logger with a console handler and apply env level.
+  pub fn init_global_from_env() -> Result<(), super::InitError> {
+    let logger = Logger::builder()
+      .name("lambda-rs")
+      .level(LogLevel::INFO)
+      .with_handler(Box::new(crate::handler::ConsoleHandler::new("lambda-rs")))
+      .build();
+    apply_env_level(&logger, Some("LAMBDA_LOG"));
+    super::Logger::init(logger)
+  }
+}
 /// Returns whether the global logger would log at `level`.
 pub fn enabled(level: LogLevel) -> bool {
   Logger::global().compare_levels(level)
@@ -425,4 +517,57 @@ mod tests {
     // If guard fails, formatting Boom would panic.
     super::trace!("{}", Boom);
   }
+
+  #[test]
+  fn builder_sets_name_level_and_handlers() {
+    #[derive(Default)]
+    struct Capture {
+      out: Arc<Mutex<Vec<String>>>,
+    }
+    impl handler::Handler for Capture {
+      fn log(&self, record: &Record) {
+        self
+          .out
+          .lock()
+          .unwrap()
+          .push(format!("{}:{}", record.target, record.level as u8));
+      }
+    }
+
+    let out = Arc::new(Mutex::new(Vec::new()));
+    let logger = Logger::builder()
+      .name("builder-app")
+      .level(LogLevel::WARN)
+      .with_handler(Box::new(Capture { out: out.clone() }))
+      .build();
+
+    logger.info("drop".to_string());
+    logger.error("keep".to_string());
+
+    let v = out.lock().unwrap();
+    assert_eq!(v.len(), 1);
+    assert_eq!(v[0], "builder-app:4"); // ERROR => 4 per to_u8 mapping
+  }
+
+  #[test]
+  fn env_parse_and_apply_level() {
+    // no panic if env missing
+    super::env::apply_env_level(
+      &Logger::new(LogLevel::TRACE, "tmp"),
+      Some("__NOT_SET__"),
+    );
+
+    assert_eq!(super::env::parse_level("trace"), Some(LogLevel::TRACE));
+    assert_eq!(super::env::parse_level("DEBUG"), Some(LogLevel::DEBUG));
+    assert_eq!(super::env::parse_level("warning"), Some(LogLevel::WARN));
+    assert_eq!(super::env::parse_level("nope"), None);
+
+    // apply
+    let logger = Logger::new(LogLevel::ERROR, "tmp");
+    std::env::set_var("LAMBDA_LOG", "info");
+    super::env::apply_env_level(&logger, Some("LAMBDA_LOG"));
+    assert!(logger.compare_levels(LogLevel::INFO));
+    // restore
+    std::env::remove_var("LAMBDA_LOG");
+  }
 }