refactor!: logger builder (#124)

Signed-off-by: tison <wander4096@gmail.com>

Author: tisonkun

.github/workflows/ci.yml

@@ -79,6 +79,7 @@ jobs:
         run: |
           set -x
           cargo run --example simple_stdout
+          cargo run --example log_with_logger
           cargo run --example multiple_dispatches
           cargo run --example custom_layout_filter
           cargo run --no-default-features --example simple_stdout

CHANGELOG.md

@@ -10,6 +10,8 @@ All notable changes to this project will be documented in this file.
 * `Append::flush` is now fallible.
 * `Diagnostic`'s and `Visitor`'s `visit` methods are fallible.
 * `NonBlocking` related types and the feature flag are now private.
+* `logforth::Builder` is renamed to `logforth::LoggerBuilder`.
+* `LoggerBuilder` has no longer an option to configure the global `max_level`. Check its documentation for more details.
 * Constructing `RollingFile` and `Syslog` appender is heavily simplified.
 
 Before:
@@ -75,6 +77,7 @@ fn construct_syslog() {
 
 * Add `LogfmtLayout` to support logfmt format.
 * Add `GoogleStructuredLogLayout` to support Google structured log format.
+* `LoggerBuilder` now has a `build` method to construct the `Logger` for use.
 
 ## [0.23.1] 2025-03-23
 

Cargo.lock

@@ -56,7 +56,7 @@ internal-serde = ["dep:serde", "log/kv_serde", "jiff/serde"]
 anyhow = { version = "1.0" }
 env_filter = { version = "0.1.1" }
 jiff = { version = "0.2" }
-log = { version = "0.4", features = ["std", "kv"] }
+log = { version = "0.4.27", features = ["std", "kv"] }
 
 # Optional dependencies
 colored = { version = "3.0", optional = true }
@@ -91,6 +91,11 @@ doc-scrape-examples = true
 name = "simple_stdout"
 path = "examples/simple_stdout.rs"
 
+[[example]]
+doc-scrape-examples = true
+name = "log_with_logger"
+path = "examples/log_with_logger.rs"
+
 [[example]]
 doc-scrape-examples = true
 name = "json_stdout"

Cargo.toml

@@ -0,0 +1,26 @@
+// Copyright 2024 FastLabs Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use log::LevelFilter;
+
+fn main() {
+    log::set_max_level(LevelFilter::Trace);
+    let l = logforth::stdout().build();
+
+    log::error!(logger: l, "Hello error!");
+    log::warn!(logger: l, "Hello warn!");
+    log::info!(logger: l, "Hello info!");
+    log::debug!(logger: l, "Hello debug!");
+    log::trace!(logger: l, "Hello trace!");
+}

examples/log_with_logger.rs

@@ -1,3 +1,3 @@
-# Rolling File Appender
+# Journald Appender
 
 This appender is a remix of [tracing-journald](https://crates.io/crates/tracing-journald) and [systemd-journal-logger](https://crates.io/crates/systemd-journal-logger), with several modifications to fit this crate's needs.

src/append/journald/README.md

@@ -32,6 +32,7 @@ pub enum Rotation {
 }
 
 impl Rotation {
+    /// Get the next date timestamp based on the current date and rotation policy.
     pub fn next_date_timestamp(&self, current_date: &Zoned) -> Option<usize> {
         let timestamp_round = ZonedRound::new().mode(RoundMode::Trunc);
 
@@ -50,6 +51,7 @@ impl Rotation {
         Some(next_date.timestamp().as_millisecond() as usize)
     }
 
+    /// Get the date format string for the rotation policy.
     pub fn date_format(&self) -> &'static str {
         match *self {
             Rotation::Minutely => "%F-%H-%M",

src/append/rolling_file/rotation.rs

@@ -36,6 +36,7 @@ pub trait Visitor {
 
 /// A trait representing a Mapped Diagnostic Context (MDC) that provides diagnostic key-values.
 pub trait Diagnostic: fmt::Debug + Send + Sync + 'static {
+    /// Visits the MDC key-values with the provided visitor.
     fn visit(&self, visitor: &mut dyn Visitor) -> anyhow::Result<()>;
 }
 

src/diagnostic/mod.rs

@@ -34,10 +34,12 @@ pub struct StaticDiagnostic {
 }
 
 impl StaticDiagnostic {
+    /// Creates a new [`StaticDiagnostic`] instance with a prebuilt key-value store.
     pub fn new(kvs: BTreeMap<String, String>) -> Self {
         Self { kvs }
     }
 
+    /// Inserts a key-value pair into the static diagnostic .
     pub fn insert<K, V>(&mut self, key: K, value: V)
     where
         K: Into<String>,
@@ -46,6 +48,7 @@ impl StaticDiagnostic {
         self.kvs.insert(key.into(), value.into());
     }
 
+    /// Remove a key-value pair from the static diagnostic.
     pub fn remove(&mut self, key: &str) {
         self.kvs.remove(key);
     }

src/diagnostic/static_global.rs

@@ -36,6 +36,7 @@ thread_local! {
 pub struct ThreadLocalDiagnostic {}
 
 impl ThreadLocalDiagnostic {
+    /// Inserts a key-value pair into the thread local diagnostic .
     pub fn insert<K, V>(key: K, value: V)
     where
         K: Into<String>,
@@ -46,6 +47,7 @@ impl ThreadLocalDiagnostic {
         });
     }
 
+    /// Removes a key-value pair from the thread local diagnostic.
     pub fn remove(key: &str) {
         CONTEXT.with(|map| {
             map.borrow_mut().remove(key);