logger-nx 0.2.0

A high-performance hourly-rotating file logger implementing the `log` facade, with TTL-based cleanup. Behaviorally equivalent to @imcooder/node-logger.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! # logger-nx
//!
//! A high-performance hourly-rotating file logger for Rust, implementing the
//! [`log`] facade.  Behaviorally equivalent to the Node.js
//! [`@imcooder/node-logger`](https://github.com/imcooder/node-logger) library.
//!
//! ## Features
//!
//! - Active log written to `<app_name>.log`
//! - Every hour the active file is renamed to `<app_name>.log.YYYYMMDDHH`
//! - Files older than `ttl_hours` (default **72 h**) are deleted automatically
//! - All I/O runs on a dedicated background thread (lock-free channel) —
//!   calling threads are **never** blocked
//! - Zero unsafe code
//!
//! ## Log format
//!
//! ```text
//! [2026-04-21 10:28:35.123] [INFO] my-app - Application started
//! ```
//!
//! ## Quick start
//!
//! ```rust,no_run
//! use logger_nx::{Config, init};
//! use log::LevelFilter;
//! use std::path::PathBuf;
//!
//! init(Config {
//!     app_name: "my-app".to_string(),
//!     log_dir: PathBuf::from("/var/log/my-app"),
//!     ttl_hours: 72,
//!     level: LevelFilter::Info,
//!     console: true,
//! }).expect("logger init failed");
//!
//! log::info!("Application started");
//! log::warn!("Low disk space");
//! log::error!("Connection failed: {}", "timeout");
//!
//! // Before process exit:
//! logger_nx::shutdown();
//! ```

mod cleaner;
mod formatter;
mod logger;

pub use logger::{Config, Logger};

use log::SetLoggerError;
use std::sync::OnceLock;

static LOGGER: OnceLock<Logger> = OnceLock::new();

/// Initialise the global logger.
///
/// Call **once** at application startup.  Returns `Err` if another logger has
/// already been registered via the `log` crate.
///
/// # Example
/// ```rust,no_run
/// use logger_nx::{Config, init};
/// use log::LevelFilter;
/// use std::path::PathBuf;
///
/// init(Config {
///     app_name: "my-app".to_string(),
///     log_dir: PathBuf::from("/tmp/my-app-logs"),
///     ttl_hours: 72,
///     level: LevelFilter::Info,
///     console: false,
/// }).unwrap();
/// ```
pub fn init(config: Config) -> Result<(), SetLoggerError> {
    let level = config.level;
    let logger = LOGGER.get_or_init(|| Logger::new(config));
    log::set_logger(logger)?;
    log::set_max_level(level);
    Ok(())
}

/// Flush pending writes and stop the background I/O thread gracefully.
///
/// Waits up to 2 seconds for the writer thread to drain.  Call this before
/// process exit.
///
/// # Example
/// ```rust,no_run
/// logger_nx::shutdown();
/// ```
pub fn shutdown() {
    if let Some(logger) = LOGGER.get() {
        logger.shutdown();
    }
}

/// Convenience: build a [`Config`] with sensible defaults and a single call.
///
/// ```rust,no_run
/// logger_nx::init(logger_nx::config("my-app", "/var/log/my-app")).unwrap();
/// ```
pub fn config(app_name: impl Into<String>, log_dir: impl Into<std::path::PathBuf>) -> Config {
    Config {
        app_name: app_name.into(),
        log_dir: log_dir.into(),
        ..Config::default()
    }
}

#[cfg(test)]
mod tests;