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.
- 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
All things to do with colours and their output to the terminal.
This module handles environment variable interactions.
This module contains the different methods and handlers for what to do when a log file already exists.
This module contains all the macros for this crate.
Convenience functions for working with time and timestamps for logging.
Macros
Structs
The global logger.
The logger struct. This is the main struct that is used to log messages.
Enums
The log level.