log4rs is a highly configurable logging framework modeled after Java’sLogback and log4j libraries.

§Architecture

The basic units of configuration areappenders,encoders,filters, andloggers.

§Appenders

An appender takes a log record and logs it somewhere, for example, to afile, the console, or the syslog.

Implementations:

• console: requires theconsole_appender feature.
• file: requires thefile_appender feature.
• rolling_file: requires therolling_file_appender feature and can be configured with thecompound_policy.
  • compound: requires thecompound_policy feature
    • Rollers
      • delete: requires thedelete_roller feature
      • fixed_window: requires thefixed_window_roller feature
    • Triggers
      • size: requires thesize_trigger feature
      • time: requires thetime_trigger feature

§Encoders

An encoder is responsible for taking a log record, transforming it into theappropriate output format, and writing it out. An appender will normallyuse an encoder internally.

Implementations:

• pattern: requires thepattern_encoder feature
• json: requires thejson_encoder feature

§Filters

Filters are associated with appenders and, like the name would suggest,filter log events coming into that appender.

Implementations:

• threshold: requires thethreshold_filter feature

§Loggers

A log event is targeted at a specific logger, which are identified bystring names. The logging macros built in to thelog crate set the loggerof a log event to the one identified by the module containing theinvocation location.

Loggers form a hierarchy: logger names are divided into components by “::”.One logger is the ancestor of another if the first logger’s component listis a prefix of the second logger’s component list.

Loggers are associated with a maximum log level. Log events for that loggerwith a level above the maximum will be ignored. The maximum log level forany logger can be configured manually; if it is not, the level will beinherited from the logger’s parent.

Loggers are also associated with a set of appenders. Appenders can beassociated directly with a logger. In addition, the appenders of thelogger’s parent will be associated with the logger unless the logger hasitsadditive set tofalse. Log events sent to the logger that are notfiltered out by the logger’s maximum log level will be sent to allassociated appenders.

The “root” logger is the ancestor of all other loggers. Since it has noancestors, its additivity cannot be configured.

§Configuration

For a detailed breakdown on configuration, refer to theconfig module.

log4rs makes heavy use of Cargo features to enable consumers to pick thefunctionality they wish to use. File-based configuration requires thefilefeature, and each file format requires its own feature as well. In addition,each component has its own feature. For example, YAML support requires theyaml_format feature and the console appender requires theconsole_appender feature.

By default, theall_components,gzip,file, andyaml_format featuresare enabled.

As a convenience, theall_components feature activates all logger components.

§Examples

§Configuration via a YAML file

# Scan this file for changes every 30 secondsrefresh_rate: 30 secondsappenders:  # An appender named "stdout" that writes to stdout  stdout:    kind: console  # An appender named "requests" that writes to a file with a custom pattern encoder  requests:    kind: file    path: "log/requests.log"    encoder:      pattern: "{d} - {m}{n}"# Set the default logging level to "warn" and attach the "stdout" appender to the rootroot:  level: warn  appenders:    - stdoutloggers:  # Raise the maximum log level for events sent to the "app::backend::db" logger to "info"  app::backend::db:    level: info  # Route log events sent to the "app::requests" logger to the "requests" appender,  # and *not* the normal appenders installed at the root  app::requests:    level: info    appenders:      - requests    additive: false

Add the following in your application initialization.

log4rs::init_file("log4rs.yml", Default::default()).unwrap();

§Programmatically constructing a configuration:

uselog::LevelFilter;uselog4rs::append::console::ConsoleAppender;uselog4rs::append::file::FileAppender;uselog4rs::encode::pattern::PatternEncoder;uselog4rs::config::{Appender, Config, Logger, Root};fnmain() {letstdout = ConsoleAppender::builder().build();letrequests = FileAppender::builder()        .encoder(Box::new(PatternEncoder::new("{d} - {m}{n}")))        .build("log/requests.log")        .unwrap();letconfig = Config::builder()        .appender(Appender::builder().build("stdout", Box::new(stdout)))        .appender(Appender::builder().build("requests", Box::new(requests)))        .logger(Logger::builder().build("app::backend::db", LevelFilter::Info))        .logger(Logger::builder()            .appender("requests")            .additive(false)            .build("app::requests", LevelFilter::Info))        .build(Root::builder().appender("stdout").build(LevelFilter::Warn))        .unwrap();lethandle = log4rs::init_config(config).unwrap();// use handle to change logger configuration at runtime}

For more examples see theexamples.