+
+pub enum LogLevel {
+ Error,
+ Warn,
+ Info,
+ Debug,
+ Trace,
+}An enum representing the available verbosity levels of the logging framework
+
+
A LogLevel may be compared directly to a LogLevelFilter.
+
Variants
+Error | The "error" level.
+
+ Designates very serious errors.
+ |
Warn | The "warn" level.
+
+ Designates hazardous situations.
+ |
Info | The "info" level.
+
+ Designates useful information.
+ |
Debug | The "debug" level.
+
+ Designates lower priority information.
+ |
Trace | The "trace" level.
+
+ Designates very low priority, often extremely verbose, information.
+ |
Methods
+
Returns the most verbose logging level.
+
+
Converts the LogLevel to the equivalent LogLevelFilter.
+
Trait Implementations
+
fn ne(&self, other: &Rhs) -> bool
+
+
fn ne(&self, other: &Rhs) -> bool
+
+
fn lt(&self, other: &Rhs) -> bool
+
fn le(&self, other: &Rhs) -> bool
+
fn gt(&self, other: &Rhs) -> bool
+
fn ge(&self, other: &Rhs) -> bool
+
+
fn lt(&self, other: &Rhs) -> bool
+
fn le(&self, other: &Rhs) -> bool
+
fn gt(&self, other: &Rhs) -> bool
+
fn ge(&self, other: &Rhs) -> bool
+
Derived Implementations
+
+
+pub enum LogLevelFilter {
+ Off,
+ Error,
+ Warn,
+ Info,
+ Debug,
+ Trace,
+}An enum representing the available verbosity level filters of the logging
+framework.
+
+
A LogLevelFilter may be compared directly to a LogLevel.
+
Variants
+Off | A level lower than all log levels.
+ |
Error | Corresponds to the Error log level.
+ |
Warn | Corresponds to the Warn log level.
+ |
Info | Corresponds to the Trace log level.
+ |
Debug | Corresponds to the Debug log level.
+ |
Trace | Corresponds to the Trace log level.
+ |
Methods
+
Returns the most verbose logging level filter.
+
+
Converts self to the equivalent LogLevel.
+
+
Returns None if self is LogLevelFilter::Off.
+
Trait Implementations
+
fn ne(&self, other: &Rhs) -> bool
+
+
fn ne(&self, other: &Rhs) -> bool
+
+
fn lt(&self, other: &Rhs) -> bool
+
fn le(&self, other: &Rhs) -> bool
+
fn gt(&self, other: &Rhs) -> bool
+
fn ge(&self, other: &Rhs) -> bool
+
+
fn lt(&self, other: &Rhs) -> bool
+
fn le(&self, other: &Rhs) -> bool
+
fn gt(&self, other: &Rhs) -> bool
+
fn ge(&self, other: &Rhs) -> bool
+
Derived Implementations
+
+
+pub fn max_log_level() -> LogLevelFilter
Returns the current maximum log level.
+
+
The log!, error!, warn!, info!, debug!, and trace! macros check
+this value and discard any message logged at a higher level. The maximum
+log level is set by the MaxLogLevel token passed to loggers.
+
pub fn set_logger<M>(make_logger: M) -> Result<(), SetLoggerError> where M: FnOnce(MaxLogLevelFilter) -> Box<Log>
Sets the global logger.
+
+
The make_logger closure is passed a MaxLogLevel object, which the
+logger should use to keep the global maximum log level in sync with the
+highest log level that the logger will not ignore.
+
+
This function may only be called once in the lifetime of a program. Any log
+events that occur before the call to set_logger completes will be
+ignored.
+
+
This function does not typically need to be called manually. Logger
+implementations should provide an initialization method that calls
+set_logger internally.
+
A lightweight logging facade.
+
+
A logging facade provides a single logging API that abstracts over the
+actual logging implementation. Libraries can use the logging API provided
+by this crate, and the consumer of those libraries can choose the logging
+framework that is most suitable for its use case.
+
+
If no logging implementation is selected, the facade falls back to a "noop"
+implementation that ignores all log messages. The overhead in this case
+is very small - just an integer load, comparison and jump.
+
+
A log request consists of a target, a level, and a body. A target is a
+string which defaults to the module path of the location of the log
+request, though that default may be overridden. Logger implementations
+typically use the target to filter requests based on some user
+configuration.
+
+
+
+
Libraries should link only to the log crate, and use the provided
+macros to log whatever information will be useful to downstream consumers.
+
+
+#[macro_use]
+extern crate log;
+
+pub fn shave_the_yak(yak: &Yak) {
+ info!(target: "yak_events", "Commencing yak shaving for {:?}", yak);
+
+ loop {
+ match find_a_razor() {
+ Ok(razor) => {
+ info!("Razor located: {}", razor);
+ yak.shave(razor);
+ break;
+ }
+ Err(err) => {
+ warn!("Unable to locate a razor: {}, retrying", err);
+ }
+ }
+ }
+}
+
+
+
+
Executables should chose a logging framework and initialize it early in the
+runtime of the program. Logging frameworks will typically include a
+function to do this. Any log messages generated before the framework is
+initialized will be ignored.
+
+
The executable itself may use the log crate to log as well.
+
+
+
The logging system may only be initialized once.
+
+
+#[macro_use]
+extern crate log;
+extern crate my_logger;
+
+fn main() {
+ my_logger::init();
+
+ info!("starting up");
+
+
+}
+
+
+
+
Loggers implement the Log trait. Here's a very basic example that simply
+logs all messages at the Error, Warn or Info levels to stdout:
+
+extern crate log;
+
+use log::{LogRecord, LogLevel, LogMetadata};
+
+struct SimpleLogger;
+
+impl log::Log for SimpleLogger {
+ fn enabled(&self, metadata: &LogMetadata) -> bool {
+ metadata.level() <= LogLevel::Info
+ }
+
+ fn log(&self, record: &LogRecord) {
+ if self.enabled(record.metadata()) {
+ println!("{} - {}", record.level(), record.args());
+ }
+ }
+}
+
+
+
Loggers are installed by calling the set_logger function. It takes a
+closure which is provided a MaxLogLevel token and returns a Log trait
+object. The MaxLogLevel token controls the global maximum log level. The
+logging facade uses this as an optimization to improve performance of log
+messages at levels that are disabled. In the case of our example logger,
+we'll want to set the maximum log level to Info, since we ignore any
+Debug or Trace level log messages. A logging framework should provide a
+function that wraps a call to set_logger, handling initialization of the
+logger:
+
+pub fn init() -> Result<(), SetLoggerError> {
+ log::set_logger(|max_log_level| {
+ max_log_level.set(LogLevelFilter::Info);
+ Box::new(SimpleLogger)
+ })
+}
+
+
+
+ | 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! |
+
+ The standard logging macro.
+
+ |
+
+
+
+ | log_enabled! |
+
+ Determines if a message logged at the specified level in that module will
+be logged.
+
+ |
+
+
+
+ | trace! |
+
+ Logs a message at the trace level.
+
+ |
+
+
+
+ | warn! |
+
+ Logs a message at the warn level.
+
+ |
+
+
+
+
+ | LogLocation |
+
+ The location of a log message.
+
+ |
+
+
+
+ | LogMetadata |
+
+ Metadata about a log message.
+
+ |
+
+
+
+ | LogRecord |
+
+ The "payload" of a log message.
+
+ |
+
+
+
+ | MaxLogLevelFilter |
+
+ A token providing read and write access to the global maximum log level
+filter.
+
+ |
+
+
+
+ | SetLoggerError |
+
+ The type returned by set_logger if set_logger has already been called.
+
+ |
+
+
+
+
+ | LogLevel |
+
+ An enum representing the available verbosity levels of the logging framework
+
+ |
+
+
+
+ | LogLevelFilter |
+
+ An enum representing the available verbosity level filters of the logging
+framework.
+
+ |
+
+
+
+
+ | Log |
+
+ A trait encapsulating the operations required of a logger
+
+ |
+
+
+
+
+ | max_log_level |
+
+ Returns the current maximum log level.
+
+ |
+
+
+
+ | set_logger |
+
+ Sets the global logger.
+
+ |
+
+
+
+
+
+macro_rules! debug {
+ (target: $target:expr, $($arg:tt)*) => (
+ log!(target: $target, $crate::LogLevel::Debug, $($arg)*);
+ );
+ ($($arg:tt)*) => (
+ log!($crate::LogLevel::Debug, $($arg)*);
+ )
+}
+
+Logs a message at the debug level.
+
+
Logging at this level is disabled if any of the following cfgs are present:
+log_level = "off", log_level = "error", log_level = "warn",
+or log_level = "info".
+
+macro_rules! error {
+ (target: $target:expr, $($arg:tt)*) => (
+ log!(target: $target, $crate::LogLevel::Error, $($arg)*);
+ );
+ ($($arg:tt)*) => (
+ log!($crate::LogLevel::Error, $($arg)*);
+ )
+}
+
+Logs a message at the error level.
+
+
Logging at this level is disabled if the log_level = "off" cfg is
+present.
+
+macro_rules! info {
+ (target: $target:expr, $($arg:tt)*) => (
+ log!(target: $target, $crate::LogLevel::Info, $($arg)*);
+ );
+ ($($arg:tt)*) => (
+ log!($crate::LogLevel::Info, $($arg)*);
+ )
+}
+
+Logs a message at the info level.
+
+
Logging at this level is disabled if any of the following cfgs are present:
+log_level = "off", log_level = "error", or
+log_level = "warn".
+
+macro_rules! log {
+ (target: $target:expr, $lvl:expr, $($arg:tt)+) => ({
+ static LOC: $crate::LogLocation = $crate::LogLocation {
+ __line: line!(),
+ __file: file!(),
+ __module_path: module_path!(),
+ };
+ let lvl = $lvl;
+ if !cfg!(log_level = "off") &&
+ (lvl <= $crate::LogLevel::Error || !cfg!(log_level = "error")) &&
+ (lvl <= $crate::LogLevel::Warn || !cfg!(log_level = "warn")) &&
+ (lvl <= $crate::LogLevel::Debug || !cfg!(log_level = "debug")) &&
+ (lvl <= $crate::LogLevel::Info || !cfg!(log_level = "info")) &&
+ lvl <= $crate::max_log_level() {
+ $crate::__log(lvl, $target, &LOC, format_args!($($arg)+))
+ }
+ });
+ ($lvl:expr, $($arg:tt)+) => (log!(target: module_path!(), $lvl, $($arg)+))
+}
+
+The standard logging macro.
+
+
This macro will generically log with the specified LogLevel and format!
+based argument list.
+
+
The log_level cfg can be used to statically disable logging at various
+levels.
+
+macro_rules! log_enabled {
+ (target: $target:expr, $lvl:expr) => ({
+ let lvl = $lvl;
+ !cfg!(log_level = "off") &&
+ (lvl <= $crate::LogLevel::Error || !cfg!(log_level = "error")) &&
+ (lvl <= $crate::LogLevel::Warn || !cfg!(log_level = "warn")) &&
+ (lvl <= $crate::LogLevel::Debug || !cfg!(log_level = "debug")) &&
+ (lvl <= $crate::LogLevel::Info || !cfg!(log_level = "info")) &&
+ lvl <= $crate::max_log_level() &&
+ $crate::__enabled(lvl, $target)
+ });
+ ($lvl:expr) => (log_enabled!(target: module_path!(), $lvl))
+}
+
+Determines if a message logged at the specified level in that module will
+be logged.
+
+
This can be used to avoid expensive computation of log message arguments if
+the message would be ignored anyway.
+
+
+use log::LogLevel::Debug;
+
+if log_enabled!(Debug) {
+ debug!("expensive debug data: {}", expensive_call());
+}
+
+
+macro_rules! trace {
+ (target: $target:expr, $($arg:tt)*) => (
+ log!(target: $target, $crate::LogLevel::Trace, $($arg)*);
+ );
+ ($($arg:tt)*) => (
+ log!($crate::LogLevel::Trace, $($arg)*);
+ )
+}
+
+Logs a message at the trace level.
+
+
Logging at this level is disabled if any of the following cfgs are present:
+log_level = "off", log_level = "error", log_level = "warn",
+log_level = "info", or log_level = "debug".
+
+macro_rules! warn {
+ (target: $target:expr, $($arg:tt)*) => (
+ log!(target: $target, $crate::LogLevel::Warn, $($arg)*);
+ );
+ ($($arg:tt)*) => (
+ log!($crate::LogLevel::Warn, $($arg)*);
+ )
+}
+
+Logs a message at the warn level.
+
+
Logging at this level is disabled if any of the following cfgs are present:
+log_level = "off" or log_level = "error".
+
pub struct LogLocation {
+ // some fields omitted
+}The location of a log message.
+
+
+
The fields of this struct are public so that they may be initialized by the
+log! macro. They are subject to change at any time and should never be
+accessed directly.
+
Methods
+
The module path of the message.
+
fn file(&self) -> &str
+
The source file containing the message.
+
+
The line containing the message.
+
Trait Implementations
Derived Implementations
+
+
+pub struct LogMetadata<'a> {
+ // some fields omitted
+}Metadata about a log message.
+
Methods
+
The verbosity level of the message.
+
+
The name of the target of the directive.
+
pub struct LogRecord<'a> {
+ // some fields omitted
+}The "payload" of a log message.
+
Methods
+
+
Metadata about the log directive.
+
+
The location of the log directive.
+
+
The verbosity level of the message.
+
+
The name of the target of the directive.
+
pub struct MaxLogLevelFilter(_);
A token providing read and write access to the global maximum log level
+filter.
+
+
The maximum log level is used as an optimization to avoid evaluating log
+messages that will be ignored by the logger. Any message with a level
+higher than the maximum log level filter will be ignored. A logger should
+make sure to keep the maximum log level filter in sync with its current
+configuration.
+
Methods
+
Gets the current maximum log level filter.
+
+
Sets the maximum log level.
+
Trait Implementations
+
+
+pub struct SetLoggerError(_);
The type returned by set_logger if set_logger has already been called.
+
Trait Implementations
Derived Implementations
+
+
+pub trait Log: Sync + Send {
+ fn enabled(&self, metadata: &LogMetadata) -> bool;
+ fn log(&self, record: &LogRecord);
+}A trait encapsulating the operations required of a logger
+
Required Methods
+
+
Determines if a log message with the specified metadata would be
+logged.
+
+
This is used by the log_enabled! macro to allow callers to avoid
+expensive computation of log message arguments if the message would be
+discarded anyway.
+
Logs the LogRecord.
+
+
Note that enabled is not necessarily called before this method.
+Implementations of log should perform all necessary filtering
+internally.
+
Implementors
+
+ 