Tklog

tklog is a high-performance structured logging library for Rust [中文]

Easy to use, Efficient, Structured, Console logging, File logging, File rotation, File compression, Synchronous logging, Asynchronous logging

Features

• Functionality: Console logging, File logging, Synchronous logging, Asynchronous logging
• Flexible log level configuration: Supports trace, debug, info, warn, error, and fatal log levels.
• Customizable output formatting: Adjust the log output format, including log level tags, time format, file locations, etc.
• Log file rotation by time: Supports rotating log files by hour, day, or month.
• Log file rotation by size: Automatically rotates log files based on file size.
• Hybrid time and size-based log rotation: Supports mixed log rotation based on both time and size.
• File count management: Allows setting a maximum number of backup log files and automatically deletes old logs to avoid excessive file accumulation.
• File compression: Supports compressing archived log files.
• Supports the official logging library’s standard API.
• Supports independent log parameters for individual modules.
• Supports independent log parameters for different log levels.
• Supports setting the log level using the environment variable RUST_LOG.

---

official website

Github

crates.io

---

Simple Usage Description

Use tklog

[dependencies]
tklog = "0.3.0"   #   "0.x.x" current version

The simplest way to use tklog involves direct macro calls:

use tklog::{trace, debug, error, fatal, info, warn};
fn testlog() {
    trace!("trace>>>>", "aaaaaaaaa", 1, 2, 3, 4);
    debug!("debug>>>>", "bbbbbbbbb", 1, 2, 3, 5);
    info!("info>>>>", "ccccccccc", 1, 2, 3, 5);
    warn!("warn>>>>", "dddddddddd", 1, 2, 3, 6);
    error!("error>>>>", "eeeeeeee", 1, 2, 3, 7);
    fatal!("fatal>>>>", "ffffffff", 1, 2, 3, 8);
}

By default, it will print console log, not files. Execution Result:

[TRACE] 2024-05-26 11:47:22 testlog.rs 27:trace>>>>,aaaaaaaaa,1,2,3,4
[DEBUG] 2024-05-26 11:47:22 testlog.rs 28:debug>>>>,bbbbbbbbb,1,2,3,5
[INFO] 2024-05-26 11:47:22 testlog.rs 29:info>>>>,ccccccccc,1,2,3,5
[WARN] 2024-05-26 11:47:22 testlog.rs 30:warn>>>>,dddddddddd,1,2,3,6
[ERROR] 2024-05-26 11:47:22 testlog.rs 31:error>>>>,eeeeeeee,1,2,3,7
[FATAL] 2024-05-26 11:47:22 testlog.rs 32:fatal>>>>,ffffffff,1,2,3,8

For initialization and customization, tklog furnishes methods to configure options such as console output, log levels, formatting styles, cutting strategies, and custom formatters.

use tklog::{
    sync::Logger,LEVEL, LOG,
    Format, MODE,
};

fn log_init() {
    LOG.set_console(true)       // Enables console logging
        .set_level(LEVEL::Info)  // Sets the log level; default is Debug
        .set_format(Format::LevelFlag | Format::Time | Format::ShortFileName)  // Defines structured log output with chosen details
        .set_cutmode_by_size("tklogsize.txt", 1<<20, 10, true)  // Cuts logs by file size (1 MB), keeps 10 backups, compresses backups
        .set_formatter("{level}{time} {file}:{message}\n");   // Customizes log output format; default is "{level}{time} {file}:{message}"
}

This illustrates global, singleton-style logging setup. Additionally, tklog facilitates custom multi-instance logging configurations, useful in systems requiring distinct logging structures across different components.

---

Multi-Instance Logging

tklog also accommodates multiple instances for scenarios that require distinct logging configurations. Each instance can possess its unique settings for console output, log level, file rotation, and a custom formatter.

use tklog::{
    debugs, errors, fatals, infos,
    sync::Logger,LEVEL, LOG,
    traces, warns, Format, MODE,
};
fn testmutlilog() {
    let mut log = Logger::new();
    log.set_console(true)
        .set_level(LEVEL::Debug) //Set the log level to Debug
        .set_cutmode_by_time("tklogs.log", MODE::DAY, 10, true)   //Split log files daily, keep up to 10 backups, and compress them
        .set_formatter("{message} | {time} {file}{level}\n");  //Customize the log structure's output format and additional content
    let mut logger = Arc::clone(&Arc::new(Mutex::new(log)));
    let log = logger.borrow_mut();
    traces!(log, "traces>>>>", "AAAAAAAAA", 1, 2, 3, 4);
    debugs!(log, "debugs>>>>", "BBBBBBBBB", 1, 2, 3, 5);
    infos!(log, "infos>>>>", "CCCCCCCCC", 1, 2, 3, 5);
    warns!(log, "warns>>>>", "DDDDDDDDDD", 1, 2, 3, 6);
    errors!(log, "errors>>>>", "EEEEEEEE", 1, 2, 3, 7);
    fatals!(log, "fatals>>>>", "FFFFFFFF", 1, 2, 3, 8);
    thread::sleep(Duration::from_secs(1))
}

Execution Result

debugs>>>>,BBBBBBBBB,1,2,3,5 | 2024-05-26 14:13:25 testlog.rs 70[DEBUG]
infos>>>>,CCCCCCCCC,1,2,3,5 | 2024-05-26 14:13:25 testlog.rs 71[INFO]
warns>>>>,DDDDDDDDDD,1,2,3,6 | 2024-05-26 14:13:25 testlog.rs 72[WARN]
errors>>>>,EEEEEEEE,1,2,3,7 | 2024-05-26 14:13:25 testlog.rs 73[ERROR]
fatals>>>>,FFFFFFFF,1,2,3,8 | 2024-05-26 14:13:25 testlog.rs 74[FATAL]

Note: The structured log output above conforms to the format specified by "{message} | {time} {file}{level}\n". The formatter includes identifiers like {message}, {time}, {file}, {level}, and any additional text or separators outside these placeholders.

---

Detailed Usage Guide

1. Log Levels: Trace < Debug < Info < Warn < Error < Fatal.

Example:

   LOG.set_level(LEVEL::Info) //Sets the log level to Info

2. Console Logging: Enable or disable via .set_console(bool).

   LOG.set_console(false) //Disables console logging (default is true)

3. Log Formats:

Format::Nano ： No formatting
Format::Date  ： Outputs date (e.g., 2024-05-26)
Format::Time  ： Outputs time to seconds (e.g., 14:13:25)
Format::Microseconds ：Outputs time with microseconds (e.g., 18:09:17.462245)
Format::LongFileName ：Full file path with line number (e.g., tests/testlog.rs 25)
Format::ShortFileName ： Abbreviated file path with line number (e.g., testlog.rs 25)
Format::LevelFlag ： Log level marker (e.g., [Debug]).

For custom formats:

LOG.set_format(Format::LevelFlag | Format::Time | Format::ShortFileName)

4. Custom Format Strings:

Default is "{level}{time} {file}:{message}\n".

• {level}: Log level indicator, e.g., [Debug].

• {time}: Logged timestamp.

• {file}: Filename and line number.

• {message}: Log content.

Example:

   LOG.set_formatter("{message} | {time} {file}{level}\n")

Reminder: Text outside the {level}, {time}, {file}, and {message} tags is output verbatim, including delimiters, spaces, and newlines.

5. Time-Based Log File Rotation:

Modes: MODE::HOUR, MODE::DAY, MODE::MONTH.

Use .set_cutmode_by_time() with:

• File path
• Time mode
• Maximum backup count
• Compression option

Example:

   let mut log = Logger::new(); 
   log.set_cutmode_by_time("/usr/local/tklogs.log", MODE::DAY, 0, false);

This configures the log to be stored at /usr/local/tklogs.log, rotated daily, with no limit on backups, and without compressing daily logs.

Backup Naming Conventions:

• Daily:
  • tklogs_20240521.log
  • tklogs_20240522.log
• Hourly:
  • tklogs_2024052110.log
  • tklogs_2024052211.log
• Monthly:
  • tklogs_202403.log
  • tklogs_202404.log

6. Size-Based Log File Rotation:

Utilize .set_cutmode_by_size() with the following parameters:

• File path
• Roll size
• Max backups
• Compress backups

Example:

let mut log = Logger::new(); 
log.set_cutmode_by_size("tklogs.log", 100<<20, 10, true);

Here, tklogs.log denotes the path, with files rolling at 100 MB each, retaining 10 backups, and compressing them.

Backup File Naming Convention:

tklogs_1.log.gz
tklogs_2.log.gz
tklogs_3.log.gz

7. Split Log Files by Mixed Mode Based on Time and Size

Calling the .set_cutmode_by_mixed() Function, Parameters Include:

• File Path: The path to the log file.
• Specified File Roll Size: The size at which the log file should roll over.
• Time Mode: Defines the time-based rolling pattern (e.g., daily, hourly, monthly).
• Maximum Number of Backup Log Files: The maximum number of backup files to retain.
• Whether to Compress Backup Log Files: Boolean value indicating if the backup log files should be compressed.

Example

let mut log = Logger::new();
log.set_cutmode_by_mixed("/usr/local/tklogs.log", 1 << 30, MODE::DAY, 10, true);

Explanation:

The backup file path is /usr/local/tklogs.log. The log file will roll over when it reaches 1GB (1<<30) in size. The rolling time mode is set to daily backups. The parameter 10 indicates that a maximum of 10 recent backup files will be retained. The parameter true indicates that backup log files will be compressed.

Backup File Naming Format:

• Mixed Backup by Day and Size, for example:

  • tklogs_20240521_1.log
  • tklogs_20240521_2.log
  • tklogs_20240521_3.log
  • tklogs_20240521_4.log
  • tklogs_20240522_1.log
  • tklogs_20240522_2.log
  • tklogs_20240522_3.log
  • tklogs_20240522_4.log

• Mixed Backup by Hour and Size, for example:

  • tklogs_2024052110_1.log
  • tklogs_2024052110_2.log
  • tklogs_2024052110_3.log
  • tklogs_2024052211_1.log
  • tklogs_2024052211_2.log
  • tklogs_2024052211_3.log

• Mixed Backup by Month and Size, for example:

  • tklogs_202403_1.log
  • tklogs_202403_2.log
  • tklogs_202403_3.log
  • tklogs_202404_1.log
  • tklogs_202404_2.log
  • tklogs_202404_3.log

**Log Printing