Crate pokey_logger

Expand description

A simple logging library for Rust.

§Usage

First, the library must be added to the project’s Cargo.toml file.

pokey_logger = "0.3.0"

or to get the latest and greatest

pokey_logger = { git = "https://github.com/PokeyOne/pokey-logger" }

For more advanced methods see the Cargo documentation on specifying dependencies

§Usage in Rust

For complete instructions, see the rustdoc documentation. Below is a simple example.

This is an example of logging some messages. It is assumed that before this that the debug! macro, the Level type, and the LOGGER constant have been imported.

use pokey_logger::{Level, LOGGER, debug, warn};

fn main() {
    // Optionally you can configure the output log level and whether or not colours
    // are shown in the terminal
    LOGGER.set_color(true);
    LOGGER.set_level(Level::Debug);
    #[cfg(feature = "log_files")]
    if LOGGER.set_log_path("logs/server.log").is_err() {
        warn!("Could not set log path");
    }

    // This will print a debug message using the `debug!` macro. The available macros
    // are debug, info, warn, and error.
    // The usage is exactly the same as a format! or println! macro.
    debug!("Some message with the number {} in it", 4);
}

As of version 0.2.0 of the library a log file can be added. It should be noted that the library will never create directories, but it will create log files if they don’t exist. For example in the above example program, the logger would not create the logs directory, but if the logs directory existed and the file did not, it would be able to create the server.log file.

It is also valuable to note that LOGGER is a global static instance of the Logger. It is thread safe to use, but one should be careful about configuring its settings from multiple threads. If you would like separate configurations and instances, the Logger struct itself can be instantiated and passed around as the developer sees fit.

§Configuration

There are three main ways to configure the logger.

Directly through functions on the logger.
A config file using the config feature.
Using environment variables.

§Directly

Look at the documentation either through docs.rs or through the cargo doc command to find all the functions that can be called to configure the logger at run time.

§Config File

After starting your program, you can tell the logger to load a yaml config file to configure the logger. Here’s an example config file:

level: Debug
color: true
time_stamp: true
file_color: false
log_file_path: "./log/development.log"
existing_log_handler: Append

To load it, see the [Logger::load_config_file()] method.

NOTE: You will need to enable the config feature to do this. This might look something like this in your Cargo.toml file.

pokey_logger = { version = "0.3.0", features = ["config"] }

§Environment Variables

The third way to configure the logger is through environment variables. For full documentation on all the variables and what they do, see the environment::configure method. The env feature must be enabled to use environment variables, however this feature is on by default.

If you are using macros and the global [static@LOGGER] variable, then there is no need to do anything special, as the environment variables are automatically applied. To apply the environment variables to a custom logger, calling the Logger::load_env_vars function will load them.

In a command this might look like:

PL_LEVEL=info PL_COLOR=false some_program

§Features

There are a few features that can be turned off when using the crate to build a smalled binary.

§Default Features

time - Use chrono to put the time at the beginning of messages.
log_files - Allow log files to be saved.
env - Allow the use of environment variables to configure the logger.

§Optional Features

config - Allows loading of a .yml config file. Includes serde.

Modules§

color: All things to do with colours and their output to the terminal.
environment: This module handles environment variable interactions.
existing_log_handler: This module contains the different methods and handlers for what to do when a log file already exists.
logging_macros: This module contains all the macros for this crate.
time: Convenience functions for working with time and timestamps for logging.

Macros§

debug: Logs a debug message on the global logger. See [ldebug!] for logging to a specific logger.
error: Logs an error message on the global logger. See [lerror!] for logging to a specific logger.
info: Logs an info message on the global logger. See [linfo!] for logging to a specific logger.
ldebug: Logs a debug message to a specific logger. See debug! for logging to the global logger.
lerror: Logs an error message to a specific logger. See error! for logging to the global logger.
linfo: Logs an info message to a specific logger. See info! for logging to the global logger.
lwarn: Logs a warning message to a specific logger. See warn! for logging to the global logger.
warn: Logs a warning message on the global logger. See [lwarn!] for logging to a specific logger.

Structs§

LOGGER: The global logger.
Logger: The logger struct. This is the main struct that is used to log messages.

Enums§

Level: The log level.
SetLogPathError

Crate pokey_loggerCopy item path