Crate pokey_logger

source · [−]
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.

  1. Directly through functions on the logger.
  2. A config file using the config feature.
  3. 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