Slog - Structured, extensible, composable logging for Rust

slog-rs is an ecosystem of reusable components for structured, extensible, composable logging for Rust.

slog is slog-rs's main crate providing core components shared between all other parts of slog-rs ecosystem.

This is automatically generated technical documentation of slog. For information about project organization, development, help, etc. please see slog github page

This is documentation for development release of slog v2. See slog v1 documentation for previous stable release.

Core advantages over log crate

• extensible - slog crate provides core functionality: very basic and portable standard feature-set based on open traits. This allows implementing new features that can be independently published.
• composable - traits that slog exposes to provide extensibility are designed to be easy to efficiently reuse and combine. By combining different functionalities every application can specify when, where and how exactly log data.
• structured - Logging with slog is not based on just one global logger. slog's Loggers carry chain of key-value data that contains the context of logging - information that otherwise would have to be repeated in every logging statement.
• both human and machine readable - By keeping the key-value data format and retaining it's type information, meaning of logging data is preserved. Data can be serialized to machine readable formats like JSON and send it to data-mining system for further analysis etc. On the other hand, when presenting on screen, logging information can be presented in aesthetically pleasing and easy to understand way.

slog features

• performance oriented; read what makes slog fast and see: slog bench log
  • lazily evaluation through closure values
  • async IO support included: see slog-async crate
• #![no_std] support (with opt-out std cargo feature flag)
• tree-structured loggers
• modular, lightweight and very extensible
  • tiny core crate that does not pull any dependencies
  • feature-crates for specific functionality
  • using slog in library does not force users of the library to use slog (but provides additional functionality); see example how to use slog in library
• backward and forward compatibility with log crate: see slog-stdlog crate
• convenience crates:
  • logging-scopes for implicit Logger passing: see slog-scope crate
• many existing core&community provided features:
  • multiple outputs
  • filtering control
    • compile-time log level filter using cargo features (same as in log crate)
    • by level, msg, and any other meta-data
    • slog-envlogger - port of env_logger
    • terminal output, with color support: see slog-term crate
  • json
    • bunyan
  • syslog and journald support
  • run-time configuration:
    • run-time behavior change; see slog-atomic
    • run-time configuration; see slog-config crate

Notable details

Note: At compile time slog by default removes trace and debug level statements in release builds, and trace level records in debug builds. This makes trace and debug level logging records practically free, which should encourage using them freely. If you want to enable trace/debug messages or raise the compile time logging level limit, use the following in your Cargo.toml:

slog = { version = ... ,
         features = ["max_level_trace", "release_max_level_warn"] }

Due to the macro_rules limitation log macros syntax comes in several variants. See log! macro, and pay attention to ; and , details.

Root drain (passed to Logger::root) must be one that does not ever return errors. This forces user to pick error handing strategy. Drain::fuse() or Drain::ignore_res().

Where to start

Drain, Logger and log macro are the most important elements of slog.

Examples & help

Some slog-rs examples are maintained in slog-misc repository

slog-rs wiki pages contain some pages about slog-rs technical details.

Source code o other software using slog-rs can be an useful reference.

Visit slog-rs gitter channel for immediate help.