Crate goolog

source ·
Expand description

§goolog

This library provides the no_std-compatible goolog logger and some macros to simplify printing logs.

§Usage in embedded / no_std environments

Because this logger is implemented in a no_std environment, it will work with all embedded systems by default.

#![no_std]

use goolog::*;

fn main() {
    // First, we initialize the logger.
    init_logger(
        None,
        None,
        // println callback
        &|_args| {
            // something printing our args to the console
        },
    );

    // Now we define a callback, which gets called whenever anyone uses the fatal! macro.
    set_on_fatal(&|| {
        // some function to restart your embedded device
    });

    // Now you can start logging using either these library macros or the log crates ones.
}

§Features

§std

This feature will:
1. Implement the println callback using the standard library
2. Implement the on_fatal callback
3. Enable timestamps using chrono

§Example

All examples from here on will assume you have the std feature active.

use goolog::*;

fn main() {
    // Initializing the logger
    init_logger(None, None);

    // See the macros module for all possible log types.
    info!("Main"; "Initialized the goolog logger.");
}

The code above will result in the following output:

# The timestamp (first two blocks) will only be shown when
# the `std` feature is active.

29.05.2023 | 14:34:33 | Main             | INFO  | Initialized the goolog logger.

But in reality, the log message will be formatted with a color like this:

GREY | GREY | WHITE | * | WHITE

*:
    DEBUG -> Blue
    ERROR -> Red
    INFO  -> Green
    TRACE -> White
    WARN  -> Yellow

§Quality of life

When printing log lines to the console using these library macros, there are two ways to specify the target:

§Specification by macro

This is always possible. Even in combination with the second method described below.

use goolog::*;

fn main() {
    init_logger(None, None);

    info!("Main"; "Initialized the goolog logger.");
}

§Specification by constant

For this method, you will only need to specify the target once:

use goolog::*;

set_target!("Main");

fn main() {
    init_logger(None, None);

    info!("Initialized the goolog logger.");

    // You can still specify a different target
    // just for that log line.
    info!("Foo"; "Initialized the goolog logger.");
}

§Customization

Currently, there are two ways to customize your goolog logger:

§Changing the logging level

By default, the logger will log at the info level. To change this, just provide a new log level.

use goolog::*;
use goolog::log::Level;

fn main() {
    // Initializing the logger with the log level set to trace
    init_logger(Some(Level::Trace), None);

    // See the macros module for all possible log types.
    // This will only be logged if the log level is set to
    // trace.
    trace!("Main"; "Initialized the goolog logger.");
}

§Changing the length of caller names

The default target length is 16 characters. Any given name longer than that will simply be truncated. However, there are two ways to customize this behavior:

§1. Change the limit
use goolog::*;

fn main() {
    // Initialize the logger with a new target length of 32
    // characters.
    init_logger(None, Some(32));

    // ...

    // You can also change the target length at runtime.
    set_target_length(8)
}
§2. Remove the limit

To do this set the target_length to 0 using either of the two ways shown above.

But before you do this, you might consider the drawbacks: If no limit is given, the logger has no way of knowing how much space to leave for the name. Therefore, each log line will ‘bend’ around the name, which will look something like this:

29.05.2023 | 14:34:33 | Main | INFO  | Starting some very important things...
29.05.2023 | 14:34:33 | MySuperAwesomeClient | INFO  | Starting...

Re-exports§

  • pub extern crate log;

Macros§

  • debug
    This macro logs a message at the debug level.
    Debug messages indicate debugging information that is compiled out of release builds and are discouraged due to their tendency to create log noise. \
    Note: Messages passed to this macro will only be printed during debug mode.
    In case you are tired of always specifying the target, see the set_target! macro.
  • error
    This macro logs a message at the error level.
    Errors indicate a problem that needs to be investigated, but doesn’t require immediate attention.
    In case you are tired of always specifying the target, see the set_target! macro.
  • fatal
    This macro logs a message at the error level and executes the callback defined by the set_on_fatal function.
    When using the std feature, this callback will, by default, call std::process::exit(1).
    Fatal errors indicate a problem that is not recoverable.

    In case you are tired of always specifying the target, see the set_target! macro.
  • info
    This macro logs a message at the info level.
    Infos indicate important information that should be logged under normal conditions, such as services starting.
    In case you are tired of always specifying the target, see the set_target! macro.
  • set_target
    Set the target for all log calls in the current module where no target is specified.

    Note: Calling this macro creates the constant GOOLOG_TARGET.
  • trace
    This macro logs a message at the trace level.
    Trace messages indicate the steps leading up to errors and warnings, and should provide context for understanding them.
    In case you are tired of always specifying the target, see the set_target! macro.
  • warn
    This macro logs a message at the warn level.
    Warnings indicate a potential problem that may or may not require investigation. They should be used sparingly to avoid becoming meaningless.
    In case you are tired of always specifying the target, see the set_target! macro.

Structs§

Functions§

  • init_logger
    Initialize the goolog logger.

    See the library documentation for more information on the usage and customization possibilities of the goolog logger.
  • set_on_fatal
    Set the callback to be called whenever the fatal macro gets called.
  • set_target_length
    Set the space for the target to a fixed size.