1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Utilities for program-wide and customizable logging
16 //! #[macro_use] extern crate log;
19 //! debug!("this is a debug {:?}", "message");
20 //! error!("this is printed by default");
22 //! if log_enabled!(log::INFO) {
23 //! let x = 3i * 4i; // expensive computation
24 //! info!("the answer was: {:?}", x);
29 //! Assumes the binary is `main`:
32 //! $ RUST_LOG=error ./main
33 //! ERROR:main: this is printed by default
37 //! $ RUST_LOG=info ./main
38 //! ERROR:main: this is printed by default
39 //! INFO:main: the answer was: 12
43 //! $ RUST_LOG=debug ./main
44 //! DEBUG:main: this is a debug message
45 //! ERROR:main: this is printed by default
46 //! INFO:main: the answer was: 12
49 //! You can also set the log level on a per module basis:
52 //! $ RUST_LOG=main=info ./main
53 //! ERROR:main: this is printed by default
54 //! INFO:main: the answer was: 12
57 //! And enable all logging:
60 //! $ RUST_LOG=main ./main
61 //! DEBUG:main: this is a debug message
62 //! ERROR:main: this is printed by default
63 //! INFO:main: the answer was: 12
68 //! There are five macros that the logging subsystem uses:
70 //! * `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
71 //! related `format!` arguments
72 //! * `debug!(...)` - a macro hard-wired to the log level of `DEBUG`
73 //! * `info!(...)` - a macro hard-wired to the log level of `INFO`
74 //! * `warn!(...)` - a macro hard-wired to the log level of `WARN`
75 //! * `error!(...)` - a macro hard-wired to the log level of `ERROR`
77 //! All of these macros use the same style of syntax as the `format!` syntax
78 //! extension. Details about the syntax can be found in the documentation of
79 //! `std::fmt` along with the Rust tutorial/manual.
81 //! If you want to check at runtime if a given logging level is enabled (e.g. if the
82 //! information you would want to log is expensive to produce), you can use the
85 //! * `log_enabled!(level)` - returns true if logging of the given level is enabled
87 //! # Enabling logging
89 //! Log levels are controlled on a per-module basis, and by default all logging is
90 //! disabled except for `error!` (a log level of 1). Logging is controlled via the
91 //! `RUST_LOG` environment variable. The value of this environment variable is a
92 //! comma-separated list of logging directives. A logging directive is of the form:
95 //! path::to::module=log_level
98 //! The path to the module is rooted in the name of the crate it was compiled for,
99 //! so if your program is contained in a file `hello.rs`, for example, to turn on
100 //! logging for this file you would use a value of `RUST_LOG=hello`.
101 //! Furthermore, this path is a prefix-search, so all modules nested in the
102 //! specified module will also have logging enabled.
104 //! The actual `log_level` is optional to specify. If omitted, all logging will be
105 //! enabled. If specified, the it must be either a numeric in the range of 1-255, or
106 //! it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
107 //! is specified, then all logging less than or equal to that numeral is enabled.
108 //! For example, if logging level 3 is active, error, warn, and info logs will be
109 //! printed, but debug will be omitted.
111 //! As the log level for a module is optional, the module to enable logging for is
112 //! also optional. If only a `log_level` is provided, then the global log level for
113 //! all modules is set to this value.
115 //! Some examples of valid values of `RUST_LOG` are:
117 //! * `hello` turns on all logging for the 'hello' module
118 //! * `info` turns on all info logging
119 //! * `hello=debug` turns on debug logging for 'hello'
120 //! * `hello=3` turns on info logging for 'hello'
121 //! * `hello,std::option` turns on hello, and std's option logging
122 //! * `error,hello=warn` turn on global error logging and also warn for hello
124 //! # Filtering results
126 //! A RUST_LOG directive may include a regex filter. The syntax is to append `/`
127 //! followed by a regex. Each message is checked against the regex, and is only
128 //! logged if it matches. Note that the matching is done after formatting the log
129 //! string but before adding any logging meta-data. There is a single filter for all
134 //! * `hello/foo` turns on all logging for the 'hello' module where the log message
136 //! * `info/f.o` turns on all info logging where the log message includes 'foo',
137 //! 'f1o', 'fao', etc.
138 //! * `hello=debug/foo*foo` turns on debug logging for 'hello' where the log
139 //! message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc.
140 //! * `error,hello=warn/[0-9] scopes` turn on global error logging and also warn for
141 //! hello. In both cases the log message must include a single digit number
142 //! followed by 'scopes'
144 //! # Performance and Side Effects
146 //! Each of these macros will expand to code similar to:
149 //! if log_level <= my_module_log_level() {
150 //! ::log::log(log_level, format!(...));
154 //! What this means is that each of these macros are very cheap at runtime if
155 //! they're turned off (just a load and an integer comparison). This also means that
156 //! if logging is disabled, none of the components of the log will be executed.
158 #![crate_name = "log"]
159 #![unstable = "use the crates.io `log` library instead"]
161 #![crate_type = "rlib"]
162 #![crate_type = "dylib"]
163 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
164 html_favicon_url = "http://www.rust-lang.org/favicon.ico",
165 html_root_url = "http://doc.rust-lang.org/nightly/",
166 html_playground_url = "http://play.rust-lang.org/")]
168 #![allow(unknown_features)]
169 #![feature(slicing_syntax)]
170 #![feature(box_syntax)]
171 #![allow(unknown_features)] #![feature(int_uint)]
173 #![deny(missing_docs)]
177 use std::cell::RefCell;
179 use std::io::LineBufferedWriter;
186 use std::sync::{Once, ONCE_INIT};
190 use directive::LOG_LEVEL_NAMES;
197 /// Maximum logging level of a module that can be specified. Common logging
198 /// levels are found in the DEBUG/INFO/WARN/ERROR constants.
199 pub const MAX_LOG_LEVEL: u32 = 255;
201 /// The default logging level of a crate if no other is specified.
202 const DEFAULT_LOG_LEVEL: u32 = 1;
204 /// An unsafe constant that is the maximum logging level of any module
205 /// specified. This is the first line of defense to determining whether a
206 /// logging statement should be run.
207 static mut LOG_LEVEL: u32 = MAX_LOG_LEVEL;
209 static mut DIRECTIVES: *const Vec<directive::LogDirective> =
210 0 as *const Vec<directive::LogDirective>;
212 /// Optional regex filter.
213 static mut FILTER: *const Regex = 0 as *const _;
216 pub const DEBUG: u32 = 4;
218 pub const INFO: u32 = 3;
220 pub const WARN: u32 = 2;
222 pub const ERROR: u32 = 1;
225 static LOCAL_LOGGER: RefCell<Option<Box<Logger + Send>>> = {
230 /// A trait used to represent an interface to a task-local logger. Each task
231 /// can have its own custom logger which can respond to logging messages
232 /// however it likes.
234 /// Logs a single message described by the `record`.
235 fn log(&mut self, record: &LogRecord);
238 struct DefaultLogger {
239 handle: LineBufferedWriter<io::stdio::StdWriter>,
242 /// Wraps the log level with fmt implementations.
243 #[derive(Copy, PartialEq, PartialOrd)]
244 pub struct LogLevel(pub u32);
246 impl fmt::Show for LogLevel {
247 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
248 fmt::String::fmt(self, fmt)
252 impl fmt::String for LogLevel {
253 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
254 let LogLevel(level) = *self;
255 match LOG_LEVEL_NAMES.get(level as uint - 1) {
256 Some(ref name) => fmt::String::fmt(name, fmt),
257 None => fmt::String::fmt(&level, fmt)
262 impl Logger for DefaultLogger {
263 fn log(&mut self, record: &LogRecord) {
264 match writeln!(&mut self.handle,
269 Err(e) => panic!("failed to log: {:?}", e),
275 impl Drop for DefaultLogger {
277 // FIXME(#12628): is panicking the right thing to do?
278 match self.handle.flush() {
279 Err(e) => panic!("failed to flush a logger: {:?}", e),
285 /// This function is called directly by the compiler when using the logging
286 /// macros. This function does not take into account whether the log level
287 /// specified is active or not, it will always log something if this method is
290 /// It is not recommended to call this function directly, rather it should be
291 /// invoked through the logging family of macros.
293 pub fn log(level: u32, loc: &'static LogLocation, args: fmt::Arguments) {
294 // Test the literal string from args against the current filter, if there
296 match unsafe { FILTER.as_ref() } {
297 Some(filter) if !filter.is_match(&args.to_string()[]) => return,
301 // Completely remove the local logger from TLS in case anyone attempts to
302 // frob the slot while we're doing the logging. This will destroy any logger
303 // set during logging.
304 let mut logger = LOCAL_LOGGER.with(|s| {
305 s.borrow_mut().take()
306 }).unwrap_or_else(|| {
307 box DefaultLogger { handle: io::stderr() } as Box<Logger + Send>
309 logger.log(&LogRecord {
310 level: LogLevel(level),
313 module_path: loc.module_path,
319 /// Getter for the global log level. This is a function so that it can be called
323 pub fn log_level() -> u32 { unsafe { LOG_LEVEL } }
325 /// Replaces the task-local logger with the specified logger, returning the old
327 pub fn set_logger(logger: Box<Logger + Send>) -> Option<Box<Logger + Send>> {
328 let mut l = Some(logger);
329 LOCAL_LOGGER.with(|slot| {
330 mem::replace(&mut *slot.borrow_mut(), l.take())
334 /// A LogRecord is created by the logging macros, and passed as the only
335 /// argument to Loggers.
337 pub struct LogRecord<'a> {
339 /// The module path of where the LogRecord originated.
340 pub module_path: &'a str,
342 /// The LogLevel of this record.
345 /// The arguments from the log line.
346 pub args: fmt::Arguments<'a>,
348 /// The file of where the LogRecord originated.
351 /// The line number of where the LogRecord originated.
357 pub struct LogLocation {
358 pub module_path: &'static str,
359 pub file: &'static str,
363 /// Tests whether a given module's name is enabled for a particular level of
364 /// logging. This is the second layer of defense about determining whether a
365 /// module's log statement should be emitted or not.
367 pub fn mod_enabled(level: u32, module: &str) -> bool {
368 static INIT: Once = ONCE_INIT;
369 INIT.call_once(init);
371 // It's possible for many threads are in this function, only one of them
372 // will perform the global initialization, but all of them will need to check
373 // again to whether they should really be here or not. Hence, despite this
374 // check being expanded manually in the logging macro, this function checks
375 // the log level again.
376 if level > unsafe { LOG_LEVEL } { return false }
378 // This assertion should never get tripped unless we're in an at_exit
379 // handler after logging has been torn down and a logging attempt was made.
380 assert!(unsafe { !DIRECTIVES.is_null() });
382 enabled(level, module, unsafe { (*DIRECTIVES).iter() })
385 fn enabled(level: u32,
387 iter: slice::Iter<directive::LogDirective>)
389 // Search for the longest match, the vector is assumed to be pre-sorted.
390 for directive in iter.rev() {
391 match directive.name {
392 Some(ref name) if !module.starts_with(&name[]) => {},
394 return level <= directive.level
398 level <= DEFAULT_LOG_LEVEL
401 /// Initialize logging for the current process.
403 /// This is not threadsafe at all, so initialization is performed through a
404 /// `Once` primitive (and this function is called from that primitive).
406 let (mut directives, filter) = match os::getenv("RUST_LOG") {
407 Some(spec) => directive::parse_logging_spec(&spec[]),
408 None => (Vec::new(), None),
411 // Sort the provided directives by length of their name, this allows a
412 // little more efficient lookup at runtime.
413 directives.sort_by(|a, b| {
414 let alen = a.name.as_ref().map(|a| a.len()).unwrap_or(0);
415 let blen = b.name.as_ref().map(|b| b.len()).unwrap_or(0);
420 let max = directives.iter().max_by(|d| d.level);
421 max.map(|d| d.level).unwrap_or(DEFAULT_LOG_LEVEL)
425 LOG_LEVEL = max_level;
427 assert!(FILTER.is_null());
429 Some(f) => FILTER = mem::transmute(box f),
433 assert!(DIRECTIVES.is_null());
434 DIRECTIVES = mem::transmute(box directives);
436 // Schedule the cleanup for the globals for when the runtime exits.
437 rt::at_exit(move |:| {
438 assert!(!DIRECTIVES.is_null());
439 let _directives: Box<Vec<directive::LogDirective>> =
440 mem::transmute(DIRECTIVES);
441 DIRECTIVES = ptr::null();
443 if !FILTER.is_null() {
444 let _filter: Box<Regex> = mem::transmute(FILTER);
445 FILTER = ptr::null();
454 use directive::LogDirective;
457 fn match_full_path() {
460 name: Some("crate2".to_string()),
464 name: Some("crate1::mod1".to_string()),
468 assert!(enabled(2, "crate1::mod1", dirs.iter()));
469 assert!(!enabled(3, "crate1::mod1", dirs.iter()));
470 assert!(enabled(3, "crate2", dirs.iter()));
471 assert!(!enabled(4, "crate2", dirs.iter()));
477 LogDirective { name: Some("crate2".to_string()), level: 3 },
478 LogDirective { name: Some("crate1::mod1".to_string()), level: 2 }
480 assert!(!enabled(2, "crate3", dirs.iter()));
484 fn match_beginning() {
486 LogDirective { name: Some("crate2".to_string()), level: 3 },
487 LogDirective { name: Some("crate1::mod1".to_string()), level: 2 }
489 assert!(enabled(3, "crate2::mod1", dirs.iter()));
493 fn match_beginning_longest_match() {
495 LogDirective { name: Some("crate2".to_string()), level: 3 },
496 LogDirective { name: Some("crate2::mod".to_string()), level: 4 },
497 LogDirective { name: Some("crate1::mod1".to_string()), level: 2 }
499 assert!(enabled(4, "crate2::mod1", dirs.iter()));
500 assert!(!enabled(4, "crate2", dirs.iter()));
506 LogDirective { name: None, level: 3 },
507 LogDirective { name: Some("crate1::mod1".to_string()), level: 2 }
509 assert!(enabled(2, "crate1::mod1", dirs.iter()));
510 assert!(enabled(3, "crate2::mod2", dirs.iter()));
516 LogDirective { name: None, level: 3 },
517 LogDirective { name: Some("crate1::mod1".to_string()), level: 0 }
519 assert!(!enabled(1, "crate1::mod1", dirs.iter()));
520 assert!(enabled(3, "crate2::mod2", dirs.iter()));