[add] updated log improvements, new examples, and new documentation.

Author: vmarcella

crates/lambda-rs-logging/README.md

@@ -2,48 +2,87 @@
 ![lambda-rs](https://img.shields.io/crates/d/lambda-rs-logging)
 ![lambda-rs](https://img.shields.io/crates/v/lambda-rs-logging)
 
-A simple logger implementation for lamba-rs crates. Inspired by
-python's [logging](https://docs.python.org/3/library/logging.html) module.
+Simple, lightweight logging for lambda-rs crates. Inspired by Python’s
+[logging](https://docs.python.org/3/library/logging.html) module.
 
 
-# Installation
-First, add the following to your `Cargo.toml`:
+## Installation
+Add to your `Cargo.toml`:
 ```toml
 [dependencies]
+# Option A: use the crate name in code as `lambda_rs_logging`
 lambda-rs-logging = "2023.1.30"
+
+# Option B: rename dependency so you can write `use logging;`
+# logging = { package = "lambda-rs-logging", version = "2023.1.30" }
 ```
 
-or run this command from your project directory:
+Or from your project directory:
 ```bash
 cargo add lambda-rs-logging
 ```
 
-# Getting started
-## Using the global logger
+Then in code, either import with the default name:
+```rust
+use lambda_rs_logging as logging;
+```
+or, if you used the rename in Cargo.toml (Option B), simply:
+```rust
+use logging; // renamed in Cargo.toml
+```
+
+## Getting Started
+### Global logger via macros
 ```rust
-use logging;
+use lambda_rs_logging as logging;
 
 fn main() {
-  logging::trace!("Hello world");
-  logging::debug!("Hello world");
-  logging::info!("Hello world");
-  logging::warn!("Hello world");
-  logging::error!("Hello world");
-  logging::fatal!("Hello world");
+  logging::trace!("trace {}", 1);
+  logging::debug!("debug {}", 2);
+  logging::info!("info {}", 3);
+  logging::warn!("warn {}", 4);
+  logging::error!("error {}", 5);
+  logging::fatal!("fatal {}", 6); // note: does not exit
 }
 ```
 
-## Using an instance of the logger
+### Custom logger instance
 ```rust
-use logging::Logger;
+use lambda_rs_logging as logging;
 
 fn main() {
-  let logger = Logger::new("my-logger");
-  logger.trace("Hello world");
-  logger.debug("Hello world");
-  logger.info("Hello world");
-  logger.warn("Hello world");
-  logger.error("Hello world");
-  logger.fatal("Hello world");
+  let logger = logging::Logger::new(logging::LogLevel::INFO, "my-app");
+  logger.add_handler(Box::new(logging::handler::ConsoleHandler::new("my-app")));
+
+  logger.info("Hello world".to_string());
+  logger.warn("Be careful".to_string());
 }
 ```
+
+### Initialize a custom global
+```rust
+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")));
+
+  // Set the global logger before any macros are used
+  logging::Logger::init(logger).expect("global logger can only be initialized once");
+
+  logging::debug!("from global");
+}
+```
+
+## 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.
+
+## Examples
+This crate ships with examples. From the repository root:
+```bash
+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
+```

crates/lambda-rs-logging/examples/01_global_macros.rs

@@ -0,0 +1,8 @@
+fn main() {
+  logging::trace!("trace example");
+  logging::debug!("debug example: {}", 42);
+  logging::info!("info example");
+  logging::warn!("warn example");
+  logging::error!("error example");
+  logging::fatal!("fatal example (no exit)");
+}

crates/lambda-rs-logging/examples/02_custom_logger.rs

@@ -0,0 +1,8 @@
+fn main() {
+  let logger = logging::Logger::new(logging::LogLevel::DEBUG, "custom");
+  logger.add_handler(Box::new(logging::handler::ConsoleHandler::new("custom")));
+
+  logger.trace("this will be filtered unless level <= TRACE".to_string());
+  logger.debug("debug from custom logger".to_string());
+  logger.info("info from custom logger".to_string());
+}

crates/lambda-rs-logging/examples/03_global_init.rs

@@ -0,0 +1,9 @@
+fn main() {
+  let logger = logging::Logger::new(logging::LogLevel::INFO, "app");
+  logger.add_handler(Box::new(logging::handler::ConsoleHandler::new("app")));
+
+  logging::Logger::init(logger)
+    .expect("global logger can only be initialized once");
+
+  logging::info!("hello from initialized global");
+}

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

@@ -1,53 +1,52 @@
 //! Log handling implementations for the logger.
 
 use std::{
-  fmt::Debug,
   fs::OpenOptions,
   io::Write,
+  sync::Mutex,
   time::SystemTime,
 };
 
-use crate::LogLevel;
+use crate::{
+  LogLevel,
+  Record,
+};
 
 /// Pluggable sink for log records emitted by the `Logger`.
-///
-/// Implementors decide how to format and where to deliver messages for each
-/// severity level.
-pub trait Handler {
-  fn trace(&mut self, message: String);
-  fn debug(&mut self, message: String);
-  fn info(&mut self, message: String);
-  fn warn(&mut self, message: String);
-  fn error(&mut self, message: String);
-  fn fatal(&mut self, message: String);
+/// Implementors decide how to format and where to deliver messages.
+pub trait Handler: Send + Sync {
+  fn log(&self, record: &Record);
 }
 
 /// A handler that logs to a file.
-
-#[derive(Debug, Clone, PartialEq, PartialOrd)]
+#[derive(Debug)]
 pub struct FileHandler {
   file: String,
-  log_buffer: Vec<String>,
+  log_buffer: Mutex<Vec<String>>,
 }
 
 impl FileHandler {
   pub fn new(file: String) -> Self {
     Self {
       file,
-      log_buffer: Vec::new(),
+      log_buffer: Mutex::new(Vec::new()),
     }
   }
+}
 
-  /// Logs a message to the file.
-  fn log(&mut self, log_level: LogLevel, message: String) {
-    let timestamp = SystemTime::now()
+impl Handler for FileHandler {
+  fn log(&self, record: &Record) {
+    let timestamp = record
+      .timestamp
       .duration_since(SystemTime::UNIX_EPOCH)
       .unwrap()
       .as_secs();
 
-    let log_message = format!("[{}]-[{:?}]: {}", timestamp, log_level, message);
+    let log_message =
+      format!("[{}]-[{:?}]: {}", timestamp, record.level, record.message);
 
-    let colored_message = match log_level {
+    // Preserve existing behavior: color codes even in file output.
+    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),
@@ -56,14 +55,15 @@ impl FileHandler {
       LogLevel::FATAL => format!("\x1B[31;1m{}\x1B[0m", log_message),
     };
 
-    self.log_buffer.push(colored_message);
+    let mut buf = self.log_buffer.lock().unwrap();
+    buf.push(colored_message);
 
     // Flush buffer every ten messages.
-    if self.log_buffer.len() < 10 {
+    if buf.len() < 10 {
       return;
     }
 
-    let log_message = self.log_buffer.join("\n");
+    let log_message = buf.join("\n");
 
     let mut file = OpenOptions::new()
       .append(true)
@@ -75,61 +75,37 @@ impl FileHandler {
       .write_all(log_message.as_bytes())
       .expect("Unable to write data");
 
-    self.log_buffer.clear();
-  }
-}
-
-impl Handler for FileHandler {
-  fn trace(&mut self, message: String) {
-    self.log(LogLevel::TRACE, message)
-  }
-
-  fn debug(&mut self, message: String) {
-    self.log(LogLevel::DEBUG, message)
-  }
-
-  fn info(&mut self, message: String) {
-    self.log(LogLevel::INFO, message)
-  }
-
-  fn warn(&mut self, message: String) {
-    self.log(LogLevel::WARN, message)
-  }
-
-  fn error(&mut self, message: String) {
-    self.log(LogLevel::ERROR, message)
-  }
-
-  fn fatal(&mut self, message: String) {
-    self.log(LogLevel::FATAL, message)
+    buf.clear();
   }
 }
 
 #[derive(Debug, Clone, PartialEq, PartialOrd)]
-/// A handler that prints colored log lines to stdout.
 pub struct ConsoleHandler {
   name: String,
 }
 
 impl ConsoleHandler {
   pub fn new(name: &str) -> Self {
-    return Self {
+    Self {
       name: name.to_string(),
-    };
+    }
   }
+}
 
-  fn log(&mut self, log_level: LogLevel, message: String) {
-    let timestamp = SystemTime::now()
+impl Handler for ConsoleHandler {
+  fn log(&self, record: &Record) {
+    let timestamp = record
+      .timestamp
       .duration_since(SystemTime::UNIX_EPOCH)
       .unwrap()
       .as_secs();
 
     let log_message = format!(
       "[{}]-[{:?}]-[{}]: {}",
-      timestamp, log_level, self.name, message
+      timestamp, record.level, self.name, record.message
     );
 
-    let colored_message = match log_level {
+    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),
@@ -141,29 +117,3 @@ impl ConsoleHandler {
     println!("{}", colored_message);
   }
 }
-
-impl Handler for ConsoleHandler {
-  fn trace(&mut self, message: String) {
-    self.log(LogLevel::TRACE, message);
-  }
-
-  fn debug(&mut self, message: String) {
-    self.log(LogLevel::DEBUG, message);
-  }
-
-  fn info(&mut self, message: String) {
-    self.log(LogLevel::INFO, message);
-  }
-
-  fn warn(&mut self, message: String) {
-    self.log(LogLevel::WARN, message);
-  }
-
-  fn error(&mut self, message: String) {
-    self.log(LogLevel::ERROR, message);
-  }
-
-  fn fatal(&mut self, message: String) {
-    self.log(LogLevel::FATAL, message);
-  }
-}