celp_sdk/logger/

log.rs

//! Provides interfaces for logging
//!
//! This includes functionality to log messages of various levels (Debug, Info, Warning, ...) to different backends,
//! as well as setting the desired log level

use std::io::Write;
use std::path::Path;

use chrono::Utc;
use colored::Colorize;
use env_logger::Env;
use log::{Level, Record};

/// SDK Log Level Enum
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    strum_macros::Display,
    strum_macros::EnumString,
    strum_macros::FromRepr,
)]
pub enum SDKLogLevel {
    /// A critical error.
    /// Maps to "Error" in log crate.
    Critical = 1,
    /// A standard error.
    /// Maps to "Error" in log crate.
    Error,
    /// A warning.
    /// Maps to "Warning in log crate.
    Warning,
    /// An informative message.
    /// Logs to "Info" in log crate.
    #[default]
    Info,
    /// A Debug message.
    /// Maps to "Debug" in log crate.
    Debug,
    /// A trace message
    /// Maps to "Trace" in log crate
    Trace,
}
// The logging environment variable used to overwrite the logging levels.
static LOG_ENV_VAR: &str = "CELP_LOG";

/// SDKLogLevel implementation
impl SDKLogLevel {
    /// Returns max logging level available.
    ///
    /// # Example
    /// ```rust,no_run
    /// use celp_sdk::logger::SDKLogLevel;
    ///
    /// let max_level = SDKLogLevel::max();
    /// ```
    pub fn max() -> SDKLogLevel {
        SDKLogLevel::Debug
    }

    /// Returns min logging level available.
    ///
    /// # Example
    /// ```rust,no_run
    /// use celp_sdk::logger::SDKLogLevel;
    ///
    /// let min_level = SDKLogLevel::min();
    /// ```
    pub fn min() -> SDKLogLevel {
        SDKLogLevel::Critical
    }
}

/// Implement 'From' and 'Into' functionality to convert the Log levels we like to the levels that the crate uses.
/// This means we can do something like: 'let log_level: Level = SDKLogLevel::Info.into();'
impl From<SDKLogLevel> for Level {
    /// Converts an SDKLogLevel value to a Level value
    ///
    /// # Example
    /// ```rust,no_run
    /// use log::Level;
    /// use celp_sdk::logger::SDKLogLevel;
    ///
    /// let converted_log_level: Level = SDKLogLevel::default().into();
    /// ```
    fn from(sdk_ll: SDKLogLevel) -> Self {
        match sdk_ll {
            SDKLogLevel::Critical => Level::Error,
            SDKLogLevel::Error => Level::Error,
            SDKLogLevel::Warning => Level::Warn,
            SDKLogLevel::Info => Level::Info,
            SDKLogLevel::Debug => Level::Debug,
            SDKLogLevel::Trace => Level::Trace,
        }
    }
}

/// Same as above, but the other way around.
impl From<Level> for SDKLogLevel {
    /// Converts a Level value to an SDKLogLevel value
    ///
    /// # Example
    /// ```rust,no_run
    /// use log::Level;
    /// use celp_sdk::logger::SDKLogLevel;
    ///
    /// let converted_log_level: SDKLogLevel = Level::Error.into();
    /// ```
    fn from(sdk_ll: Level) -> Self {
        match sdk_ll {
            Level::Error => SDKLogLevel::Error,
            Level::Warn => SDKLogLevel::Warning,
            Level::Info => SDKLogLevel::Info,
            Level::Debug => SDKLogLevel::Debug,
            Level::Trace => SDKLogLevel::Trace,
        }
    }
}

/// Initialise the logging functionality to a certain level.
///
/// # Arguments
///
/// * `module_name` - A string to denote the calling application. It can be any string. It does not have to match the exact application name.
/// * `log_level` - The level of logging to use. If not given, will use default logging level.
///
/// # Example
/// ```rust,no_run
/// use celp_sdk::logger::{SDKLogLevel, init_logger};
///
/// let app_name = "test";
/// let level = SDKLogLevel::default();
///
/// init_logger(app_name, Some(level));
/// ```
pub fn init_logger(module_name: &str, log_level: Option<SDKLogLevel>) {
    // Set default logging level (converts to "Info" for our logging levels).
    let mut converted_log_level: Level = SDKLogLevel::default().into();
    // Convert the SDKLogLevel to standard Level type
    // If a log level was specified.
    if let Some(ll) = log_level {
        // Convert the SDKLogLevel to Level.
        converted_log_level = ll.into();
    }

    // Set up a new Builder instance here so that we can ignore some of the presets like the "RUST_LOG" environment variable and such.
    let mut builder = env_logger::Builder::new();

    // Convert the 'Level' type to 'LevelFilter' type with 'to_level_filter'.
    // NOTE: After some testing, it is seen that `filter_level` is required first before setting `filter_module` or else the level filter does not get set correctly.
    builder.filter_level(converted_log_level.to_level_filter());
    // Then set the filter for the module.
    builder.filter_module(module_name, converted_log_level.to_level_filter());

    // Need to check if the custom environment variable is set first.
    if std::env::var(LOG_ENV_VAR).is_ok() {
        // Specify a custom environment variable other than the default "RUST_LOG"
        let env = Env::new().filter(LOG_ENV_VAR);
        // Set the environment variable to use for overwriting log levels.
        builder.parse_env(env);
    }
    // Set the output as stdout (env_logger uses stderr by default).
    builder.target(env_logger::Target::Stdout);

    //Format the output message.
    builder.format(|buf, record| writeln!(buf, "{}", format_log_str(record)));

    // Initialise the builder.
    builder.init();
}

/// Format the log string in a similar manner to C++ SDK logger.
/// Will output in the following format:
/// "[1970-01-01T12:34:56.012345Z] [main.rs:123] [---D---] log message"
fn format_log_str(record: &Record) -> String {
    // Get the current time.
    let now = Utc::now();
    let formatted_time = now.format("[%Y-%m-%dT%H:%M:%S%.6fZ]").to_string();
    // Get the file name or use the default string.
    let filename = record.file().unwrap_or("Unknown file path");
    // Convert to Path object to get the file name at end of string.
    let path = Path::new(filename);
    let line = record.line().unwrap_or(0);
    // Convert the log level to a str, iterator over the characters and grab the first letter.
    let sdk_log_level: SDKLogLevel = record.level().into();
    let short_log_level_char = sdk_log_level.to_string().chars().next().unwrap();
    let mut short_log_level_str = String::from("---X---");
    // Replace the "X" with the correct character.
    short_log_level_str.replace_range(3..4, &short_log_level_char.to_string());
    // Based on the log level, the string should be a different colour.
    // TODO: Confirm color choice with C++ version.
    let short_log_level_str_colored = match sdk_log_level {
        SDKLogLevel::Critical => short_log_level_str.purple(),
        SDKLogLevel::Error => short_log_level_str.red(),
        SDKLogLevel::Warning => short_log_level_str.yellow(),
        SDKLogLevel::Info => short_log_level_str.green(),
        SDKLogLevel::Debug => short_log_level_str.blue(),
        SDKLogLevel::Trace => short_log_level_str.white(),
    };

    // NOTE: Will not implement thread ID printing for now. Rust doesn't have any nice ways for this library to get the thread ID of the calling application.
    //       We would have to pss the thread ID directly from the calling application. That would just be messy.
    format!(
        "{} [{:?}:{:?}] [{}] {:?}",
        formatted_time,
        path.file_name()
            .unwrap_or(std::ffi::OsStr::new("<unknown>")),
        line,
        short_log_level_str_colored,
        record.args()
    )
}

/// The following macros convert the 'log' crates macros to use our own log levels.
///
/// | SDK      | log   |
/// |__________|_______|
/// | critical | error |
/// | error    | error |
/// | warning  | warn  |
/// | info     | info  |
/// | debug    | debug |
/// | trace    | trace |
///
pub use log::{debug as _debug, error as _error, info as _info, trace as _trace, warn as _warn};

/// # Example
/// ```rust,no_run
/// use celp_sdk::critical;
///
/// critical!("It all went terribly wrong!");
/// ```
///
#[macro_export]
macro_rules! critical {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'error!' macro
        $crate::logger::_error!($($arg)*)
    }
}

/// # Example
/// ```rust,no_run
/// use celp_sdk::error;
///
/// error!("Oh oh: {}", "details");
/// ```
#[macro_export]
macro_rules! error {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'error!' macro
        $crate::logger::_error!($($arg)*)
    }
}

/// # Example
/// ```rust,no_run
/// use celp_sdk::warning;
///
/// warning!("woopsie: {}", "details");
/// ```
#[macro_export]
macro_rules! warning {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'warning!' macro
        $crate::logger::_warn!($($arg)*)
    }
}

/// # Example
/// ```rust,no_run
/// use celp_sdk::info;
///
/// info!("I'd like to tell you about: {}", "what I'm doing now");
/// ```
#[macro_export]
macro_rules! info {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'info!' macro
        $crate::logger::_info!($($arg)*)
    }
}

/// # Example
/// ```rust,no_run
/// use celp_sdk::debug;
///
/// debug!("I know you're probably not really interested in this: {}!", "but here it is anyway");
/// ```
#[macro_export]
macro_rules! debug {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'debug!' macro
        $crate::logger::_debug!($($arg)*)
    }
}

/// # Example
/// ```rust,no_run
/// use celp_sdk::trace;
///
/// trace!("I'll inundate you with information!");
/// ```
#[macro_export]
macro_rules! trace {
    ($($arg:tt)*) => {
        // Delegate to the 'log' crates 'debug!' macro
        $crate::logger::_trace!($($arg)*)
    }
}