An opinionated library for developing and testing rust applications that use logging.
This is inspired by simple-logging implementation, with additional features meant to support development of applications (as opposed to libraries).
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.
The main program will need to set up the logger:
```rust extern crate loggy;
loggy::init(Loggy { prefix: "...", // Typically, the name of the program. showtime: true, // Or false. loglevel: LogLevel::Warn, // Or Info, or Error. }); ```
To provide user control over handling issues:
```rust
extern crate loggy;
let isissueanerror = decidebasedoncommandlinearguments(); if didissueoccur() { note!(isissueanerror, "issue occured: {}", issuedata()); provideworkaround(); } else { proceednormally(); } ```
To deal with errors in processing stages:
```rust extern crate loggy;
{ let scope = loggy::ErrorsScope::new(); runprocessingstagewithpotentialerrors(); if scope.haderrors() { return; } } continuetonextprocessingstage(); ```
To test code that emits log messages;
```rust
extern crate loggy;
testloggy!(testname, {
runsomecode();
assert_log("\
test: [
```
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.
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 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.
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.
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).
loggy is licensed under the MIT License.