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.3"
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!");
warn!("3 + 2 = {}", 5);
error!("oops!");
Output:
[2022-11-02 09:23:12.263] [info] hello, world! [2022-11-02 09:23:12.263] [warn] 3 + 2 = 5 [2022-11-02 09:23:12.263] [error] oops!
If you want to learn more advanced features such as asynchronous sink, compile-time pattern formatter, etc., please 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.
See ./examples directory for examples.
Asynchronous support
See Asynchronous combined sink.
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 formatterFullFormatter
will always format the source location information, and some formatting patterns related to source location will be available. 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 ofStringBuf
. -
log
see Compatible with log crate above. -
native
enables platform-specific components, such assink::WinDebugSink
,sink::JournaldSink
, etc. Note If the component requires additional system dependencies, then more granular features need to be enabled as well. See the documentation of the component for these details.
Supported Rust Versions
The current minimum supported Rust version is 1.56.
spdlog-rs
is built against the latest Rust stable release, it is not
guaranteed to build on Rust versions earlier than the minimum supported
version.
spdlog-rs
follows the compiler support policy that the latest stable
version and the 3 most recent minor versions before that are always
supported. For example, if the current latest Rust stable version is 1.61,
the minimum supported version will not be increased past 1.58. Increasing
the minimum supported version is not considered a semver breaking change as
long as it complies with this policy.
Significant differences from C++ spdlog
The significant differences between spdlog-rs
and C++ spdlog
1:
-
spdlog-rs
does not haveregistry
2. You don’t need to register for loggers. -
spdlog-rs
does not havebacktrace
2. -
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
andhourly_file_sink
in C++spdlog
are merged intoRotatingFileSink
inspdlog-rs
. They correspond to rotation policiesRotationPolicy::Daily
andRotationPolicy::Hourly
. -
async_logger
in C++spdlog
isAsyncPoolSink
inspdlog-rs
. This allows it to be used with synchronous sinks. -
Some sinks in C++
spdlog
are not yet implemented inspdlog-rs
. (Yes, PRs are welcome) -
…
Re-exports
Modules
log
log
crate for convenience.Macros
SourceLocation
with current source location.Structs
Logger
.Record
without lifetimes version.multi-thread
multi-thread
ThreadPool
.Enums
Constants
Functions
Arc
default logger.SPDLOG_RS_LEVEL
.LogCrateProxy
.