Crate slog [] [src]

Slog - Structured, extensible, composable logging for Rust

Features

  • easy to use
  • great performance; see: slog bench log
  • #![no_std] support (with opt-out std cargo feature flag)
  • hierarchical loggers
  • lazily evaluated values
  • modular, lightweight and very extensible
    • tiny core crate that does not pull any dependencies
    • feature-crates for specific functionality
  • backward compatibility for standard log crate (slog-stdlog crate)
    • supports logging-scopes
    • using slog in library does not force users of the library to use slog (but gives benefits); see crates/example-lib
  • drains & output formatting
    • filtering
      • 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
    • multiple outputs
    • asynchronous IO writing
    • terminal output, with color support (slog-term crate)
    • Json (slog-json crate)
      • Bunyan (slog-bunyan crate)
    • syslog (slog-syslog crate)
    • first class custom drains

Advantages over log crate

  • extensible - slog provides core functionality, and some standard feature-set. But using traits, anyone can easily implement as powerful fully-custom features, publish separately and grow slog feature-set for everyone.
  • composable - Wouldn't it be nice if you could use env_logger, but output authentication messages to syslog, while reporting errors over network in json format? With slog drains can reuse other drains! You can combine them together, chain, wrap - you name it.
  • context aware - It's not just one global logger. Hierarchical loggers carry information about context of logging. When logging an error condition, you want to know which resource was being handled, on which instance of your service, using which source code build, talking with what peer, etc. In standard log you would have to repeat this information in every log statement. In slog it will happen automatically. See slog-rs functional overview page to understand better logger and drain hierarchies and log record flow through them.
  • both human and machine readable - By keeping the key-value data format, meaning of logging data is preserved. Dump your logging to a JSON file, and send it to your data-mining system for further analysis. Don't parse it from lines of text anymore!
  • lazy evaluation and asynchronous IO included. Waiting to finish writing logging information to disk, or spending time calculating data that will be thrown away at the current logging level, are sources of big performance waste. Use AsyncStreamer drain, and closures to make your logging fast.
  • run-time configuration - AtomicSwitch drain allows changing logging behavior in the running program. You could use eg. signal handlers to change logging level or logging destinations. See signal example.

Notable details

slog by default removes at compile time 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 = "1.2", features = ["max_level_trace", "release_max_level_warn"] }

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

Root drain (passed to Logger::root) must be one that does not ever return errors, which forces user to pick error handing strategy. You can use .fuse() or .ignore_err() methods from DrainExt to do it conveniently.

Examples & help

Look at slog-rs examples in slog-misc repository

Read slog-rs wiki pages

Check sources of other software using slog-rs

Visit slog-rs gitter channel for immediate help.

Reexports

pub use ser::PushLazy;
pub use ser::ValueSerializer;
pub use ser::Serializer;
pub use ser::Serialize;

Modules

ser

Serialization

Macros

crit

Log critical level record

debug

Log debug level record

error

Log error level record

info

Log info level record

log

Log message of a given level

o

Convenience macro for building SyncMultiSerialize trait object

slog_crit

Log critical level record (alias)

slog_debug

Log debug level record (alias)

slog_error

Log error level record

slog_info

Log info level record (alias)

slog_log

Log message of a given level (alias)

slog_o

An alternative, longer-name version of o macro

slog_trace

Log trace level record (alias)

slog_warn

Log warning level record (alias)

trace

Log trace level record

warn

Log warning level record

Structs

Discard

Drain discarding everything

Duplicate

Drain duplicating records into two other Drains

Filter

Drain filtering records

Fuse

Drain panicking on error

IgnoreErr

Drain ignoring errors

LevelFilter

Drain filtering records by Record logging level

Logger

Logging handle used to execute logging statements

MapError

Drain mapping error returned by another Drain

OwnedKeyValueList

Chain of SyncMultiSerialize-s of a Logger and its ancestors

OwnedKeyValueListIterator

Iterator over OwnedKeyValue-s

Record

One logging record

Enums

DuplicateError

Logging error returned by Duplicate drain

FilterLevel

Logging filtering level

Level

Logging level associated with a logging Record

Statics

LOG_LEVEL_NAMES

Official capitalized logging (and logging filtering) level names

LOG_LEVEL_SHORT_NAMES

Official capitalized logging (and logging filtering) short level names

Traits

Drain

Logging drain

DrainExt

Convenience methods for building drains

Functions

duplicate

Duplicate records to two drains

filter

Filter by cond closure

level_filter

Filter by log level

Type Definitions

BorrowedKeyValue

Key value pair that can be part of a logging record

OwnedKeyValue

Key value pair that can be owned by Logger