loggy

An opinionated library for developing and testing rust applications that use logging.

This is inspired by simple-logging implementation, with additional features focusing on development of applications (as opposed to libraries).

Building and Testing

To build run either cargo build or cargo make build.

To test, run either RUST_TEST_THREADS=1 cargo test or cargo make test. Single thread testing is required due to the rust log facade mandating the use of a single global logger.

Examples

The main program will need to set up the logger:

extern crate loggy;
extern crate log;

log::set_logger(&Loggy {
    prefix: "...", // Typically, the name of the program.
    show_time: true, // Or false.
}).unwrap();
log::set_max_level(log::LevelFilter::Info); // Or whatever level you want.

To provide user control over handling issues:

#[macro_use]
extern crate loggy;

let is_issue_an_error = decide_based_on_command_line_arguments();
if did_issue_occur() {
    note!(is_issue_an_error, "issue occured: {}", issue_data());
    provide_workaround();
} else {
    proceed_normally();
}

To deal with errors in processing stages:

extern crate loggy;

{
    let scope = loggy::ErrorsScope::new();
    run_processing_stage_with_potential_errors();
    if scope.had_errors() {
        return;
    }
}
continue_to_next_processing_stage();

To test code that emits log messages;

#[macro_use]
extern crate loggy;

test_loggy!(test_name, {
    run_some_code();
    assert_log("\
test: [<level>] <module>: <message>
...
");
});

Motivation

This library was written to support the development of a non-trivial Rust application that uses logging. The functionality provided here was factored out, both to keep it isolated from the application itself, and in the hope it might prove useful to others.

Technically, this library is an implementation for the Rust log facade, with a few additional features thrown in. The implementation and features were designed to support a specific development workflow.

Features

As an implementation of the log facade, this library is pretty basic and standard. Messages are emitted to the standard error stream. The message format is <prefix>[<thread>]: <time> [<level]>] <module>: <message>, where the time may be omitted.

Additional features reflect the library's opinionated nature:

Logging Features

• Logging multi-line messages (that contain \n) will generate multiple log lines. The first line will include the log level in upper case (e.g., [ERROR]), all the following will specify it in lower case (e.g., [error]). The time stamp, if included, will be identical for all these lines. This makes log messages easily grep-able, countable, etc.

• It is assumed that either the program is single-threaded, or, if multi-threaded, then the main thread spawns off worker threads slaved to the main one, to perform transient tasks. Therefore, the thread index is only reported for log messages generated from the worker threads.

• In debug builds, debug messages are always emitted, regardless of the setting of the log level threshold (other messages do obey the threshold). This is under the assumption that debug builds are only used for, well, debugging. In contrast, in release builds, the threshold applies to debug messages as well. It is assumed that there would be none (or that they would be very rare), since release builds are meant for, well, release rather than debugging.

• The format of the debug messages replaces the <module>: name with <file>:<line>:. This is under the assumption that such messages would hardly ever be seen by users. Developers, on the other hand, would benefit from having the exact code location generating each message.

Development Features

• An additional todox! macro is provided, which behaves exactly like debug!. If using the cargo todox extension, this prevents leftover debugging messages from being inadvertently left in the code.

• An additional note! macro is provided, which behaves either like error! or warn!, depending on the value of its first (additional) parameter. This boolean parameter is typically derived from a command line argument (ideally, this should be automated as well). This makes it easy to allow the users to determine whether different conditions warrant aborting the program.

• Every call to error! (including calls via note!), from any thread, is counted. The errors function returns the total number of errors, and the had_errors function just returns whether any such calls occurred. This allows the program to easily decide on its final exit status.

• In addition, using ErrorsScope allows counting the errors that occur in specific regions of the code (in the current thread), also providing errors count and a had_errors test. This allows the code to easily report multiple errors from some processing stage, deferring aborting the program until the whole processing stage is done.

Testing Features

• A test_loggy! macro allows creating a test for code that emits log messages. All messages (except for debug messages) are captured to a buffer. The test should use assert_log to examine this buffer, or clear_log to explicitly discard it. Examining the log is an effective way to gain insights and verify the behavior of the tested code.

• Setting the LOGGY_MIRROR_TO_STDERR environment variable to any non-empty value will cause all messages to be emitted to the standard error stream, together with any debug messages. This places the debug messages in the context of the other messages, helping in debugging.

  Note that the standard error contents are only reported for failing tests. Well, actually, the rust mechanism for capturing the standard error seems to not work properly when the test spawns new threads, so any debug or mirrored messages emitted from worker threads will be visible even for passing tests. This isn't a show stopper given such messages and the LOGGY_MIRROR_TO_STDERR variable are only used when actively debugging an issue.

• The rust log facade mandates using a single global logger. This, combined with loggy handling multiple threads at once (counting errors, capturing messages), means that test_loggy! tests must run with RUST_TEST_THREADS=1 cargo test. This can be automated by providing an env section in Makefile.toml and running cargo make test from the command line, and similarly by providing an env section in the .travis.yml file (both methods are used by this package).

License

loggy is licensed under the MIT License.