Crate spdlog

Expand description

A fast and combinable Rust logging crate.

It is inspired by the C++ logging library spdlog, so if you are familiar with C++ spdlog, you should be able to get started with this crate quite easily. Of course, there are some differences, you can see Significant differences from C++ spdlog below.

Getting started

Add this to Cargo.toml:

[dependencies]
spdlog-rs = "0.2"

spdlog-rs is out-of-the-box, it has a default logger, so users can output logs to terminal by default without any configuration. For more details about the default logger, please read the documentation of default_logger.

The basic use of this crate is through these logging macros: trace!, debug!, info!, warn!, error!, critical! and log!, where critical! represents the most severe log messages and trace! the most verbose. Each of these macros accept format strings similarly to println!. All log macros and common types are already under prelude module.

Logger and Sink are the most important components of spdlog-rs. Make sure to read their documentation. In short, a logger contains a combination of sinks, and sinks implement writing log messages to actual targets.

Examples

use spdlog::prelude::*;

info!("hello, {}", "world");

For more examples, see ./examples directory.

Help

If you have any questions or need help while using this crate, feel free to open a discussion. For feature requests or bug reports, please open an issue.

Compatible with log crate

This is optional and is controlled by crate feature log.

The compatibility with log crate is mainly through a proxy layer LogCrateProxy. Call init_log_crate_proxy function to enable the proxy layer, and all logs from log crate will be handled by it. You can use it to output log crate logs of upstream dependencies or to quickly migrate from log crate for your projects.

LogCrateProxy forwards all logs from log crate to default_logger by default, you can call log_crate_proxy() to get a reference to this proxy to configure it.

Examples

See ./examples directory.

Configured via environment variable

Users can optionally configure the level filter of loggers via the environment variable SPDLOG_RS_LEVEL.

For more details, see the documentation of init_env_level.

Compile time filters

Log levels can be statically disabled at compile time via Cargo features. Log invocations at disabled levels will be skipped and will not even be present in the resulting binary. This level is configured separately for release and debug builds. The features are:

level-off
level-critical
level-error
level-warn
level-info
level-debug
level-trace
release-level-off
release-level-critical
release-level-error
release-level-warn
release-level-info
release-level-debug
release-level-trace

These features control the value of the STATIC_LEVEL_FILTER constant. The logging macros check this value before logging a message. By default, no levels are disabled.

For example, a crate can disable trace level logs in debug builds and trace, debug, and info level logs in release builds with features = ["level-debug", "release-level-warn"].

Crate Feature Flags

The following crate feature flags are available in addition to the filters. They are configured in your Cargo.toml.

source-location allows recording the source location of each log. When it is enabled the default formatter FullFormatter will always format the source location information. If you do not want the source location information to appear in your binary file, you may prefer not to enable it.
flexible-string improves the performance of formatting records, however contains unsafe code. For more details, see the documentation of StringBuf.
log see Compatible with log crate above.

Significant differences from C++ spdlog

The significant differences between spdlog-rs and C++ spdlog¹:

spdlog-rs does not have registry². You don’t need to register for loggers.
spdlog-rs does not have backtrace².
spdlog-rs currently does not have pattern_formatter. The solution for custom formatting log messages is to implement your own Formatter structure and then call Sink::set_formatter.
In spdlog-rs, LevelFilter is a more flexible and readable enum with logical conditions.
In spdlog-rs, there is no “_st” sinks, all sinks are “_mt”.
daily_file_sink and hourly_file_sink in C++ spdlog are merged into RotatingFileSink in spdlog-rs. They correspond to rotation policies RotationPolicy::Daily and RotationPolicy::Hourly.
Some sinks in C++ spdlog are not yet implemented in spdlog-rs. (Yes, PRs are welcome)
…