Crate spdlog

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 formatter FullFormatter 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 of StringBuf.

• log see Compatible with log crate above.

• native enables platform-specific components, such as sink::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¹:

• spdlog-rs does not have registry². You don’t need to register for loggers.

• spdlog-rs does not have backtrace².

• 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.

• async_logger in C++ spdlog is AsyncPoolSink in spdlog-rs. This allows it to be used with synchronous sinks.

• Some sinks in C++ spdlog are not yet implemented in spdlog-rs. (Yes, PRs are welcome)

• …

---

1. At the time of writing this section, the latest version of C++ spdlog is v1.9.2. ↩

2. C++ spdlog is also planned to remove it in v2.x. ↩

Re-exports

• pub use error::Error;
• pub use error::ErrorHandler;
• pub use error::Result;

Modules

• error
  Provides error types.
• formatter
  Provides formatters for sink formatting log records.
• log_cratelog
  Re-export some stuff from log crate for convenience.
• prelude
  Contains all log macros and common types.
• sink
  Provides sinks to flexibly output log messages to specified targets.
• terminal_style
  Provides stuff related to terminal style.

Macros

• critical
  Logs a message at the critical level.
• debug
  Logs a message at the debug level.
• error
  Logs a message at the error level.
• info
  Logs a message at the info level.
• log
  Logs a message.
• source_location_current
  Constructs a SourceLocation with current source location.
• trace
  Logs a message at the trace level.
• warn
  Logs a message at the warn level.

Structs

• LogCrateProxylog
  Log crate proxy.
• Logger
  A logger structure.
• LoggerBuilder
  The builder of Logger.
• Record
  Represents a log record.
• RecordOwned
  Record without lifetimes version.
• SourceLocation
  Represents a location in source code.
• ThreadPoolmulti-thread
  A thread pool for processing operations asynchronously.
• ThreadPoolBuildermulti-thread
  The builder of ThreadPool.

Enums

• Level
  An enum representing log levels.
• LevelFilter
  An enum representing log level logical filter conditions.

Constants

• STATIC_LEVEL_FILTER
  The statically resolved log level filter.

Functions

• default_logger
  Returns an Arc default logger.
• init_env_level
  Initialize environment variable level filters from environment variable SPDLOG_RS_LEVEL.
• init_env_level_from
  Initialize environment variable level filters from a specified environment variable.
• init_log_crate_proxylog
  Initialize log crate proxy.
• log_crate_proxylog
  Returns a LogCrateProxy.
• set_default_logger
  Sets the given logger as the default logger.
• swap_default_logger
  Sets the given logger as the default logger, and returns the old default logger.

Type Aliases

• StringBuf
  A string buffer type.