src/libstd/logging.rs

   1 // Copyright 2012 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.
   4 //
   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.
  10
  11 /*!
  12
  13 Logging
  14
  15 This module is used by the compiler when emitting output for the logging family
  16 of macros. The methods of this module shouldn't necessarily be used directly,
  17 but rather through the logging macros defined.
  18
  19 There are five macros that the logging subsystem uses:
  20
  21 * `log!(level, ...)` - the generic logging macro, takes a level as a u32 and any
  22                        related `format!` arguments
  23 * `debug!(...)` - a macro hard-wired to the log level of `DEBUG`
  24 * `info!(...)` - a macro hard-wired to the log level of `INFO`
  25 * `warn!(...)` - a macro hard-wired to the log level of `WARN`
  26 * `error!(...)` - a macro hard-wired to the log level of `ERROR`
  27
  28 All of these macros use the same style of syntax as the `format!` syntax
  29 extension. Details about the syntax can be found in the documentation of
  30 `std::fmt` along with the Rust tutorial/manual.
  31
  32 If you want to check at runtime if a given logging level is enabled (e.g. if the
  33 information you would want to log is expensive to produce), you can use the
  34 following macro:
  35
  36 * `log_enabled!(level)` - returns true if logging of the given level is enabled
  37
  38 ## Enabling logging
  39
  40 Log levels are controlled on a per-module basis, and by default all logging is
  41 disabled except for `error!` (a log level of 1). Logging is controlled via the
  42 `RUST_LOG` environment variable. The value of this environment variable is a
  43 comma-separated list of logging directives. A logging directive is of the form:
  44
  45 ```
  46 path::to::module=log_level
  47 ```
  48
  49 The path to the module is rooted in the name of the crate it was compiled for,
  50 so if your program is contained in a file `hello.rs`, for example, to turn on
  51 logging for this file you would use a value of `RUST_LOG=hello`. Furthermore,
  52 this path is a prefix-search, so all modules nested in the specified module will
  53 also have logging enabled.
  54
  55 The actual `log_level` is optional to specify. If omitted, all logging will be
  56 enabled. If specified, the it must be either a numeric in the range of 1-255, or
  57 it must be one of the strings `debug`, `error`, `info`, or `warn`. If a numeric
  58 is specified, then all logging less than or equal to that numeral is enabled.
  59 For example, if logging level 3 is active, error, warn, and info logs will be
  60 printed, but debug will be omitted.
  61
  62 As the log level for a module is optional, the module to enable logging for is
  63 also optional. If only a `log_level` is provided, then the global log level for
  64 all modules is set to this value.
  65
  66 Some examples of valid values of `RUST_LOG` are:
  67
  68 ```
  69 hello                // turns on all logging for the 'hello' module
  70 info                 // turns on all info logging
  71 hello=debug          // turns on debug logging for 'hello'
  72 hello=3              // turns on info logging for 'hello'
  73 hello,std::hashmap   // turns on hello, and std's hashmap logging
  74 error,hello=warn     // turn on global error logging and also warn for hello
  75 ```
  76
  77 ## Performance and Side Effects
  78
  79 Each of these macros will expand to code similar to:
  80
  81 ```rust
  82 if log_level <= my_module_log_level() {
  83     ::std::logging::log(log_level, format!(...));
  84 }
  85 ```
  86
  87 What this means is that each of these macros are very cheap at runtime if
  88 they're turned off (just a load and an integer comparison). This also means that
  89 if logging is disabled, none of the components of the log will be executed.
  90
  91 ## Useful Values
  92
  93 For convenience, if a value of `::help` is set for `RUST_LOG`, a program will
  94 start, print out all modules registered for logging, and then exit.
  95
  96 */
  97
  98 use fmt;
  99 use option::*;
 100 use rt::local::Local;
 101 use rt::logging::{Logger, StdErrLogger};
 102 use rt::task::Task;
 103
 104 /// Debug log level
 105 pub static DEBUG: u32 = 4;
 106 /// Info log level
 107 pub static INFO: u32 = 3;
 108 /// Warn log level
 109 pub static WARN: u32 = 2;
 110 /// Error log level
 111 pub static ERROR: u32 = 1;
 112
 113 /// This function is called directly by the compiler when using the logging
 114 /// macros. This function does not take into account whether the log level
 115 /// specified is active or not, it will always log something if this method is
 116 /// called.
 117 ///
 118 /// It is not recommended to call this function directly, rather it should be
 119 /// invoked through the logging family of macros.
 120 pub fn log(_level: u32, args: &fmt::Arguments) {
 121     unsafe {
 122         let optional_task: Option<*mut Task> = Local::try_unsafe_borrow();
 123         match optional_task {
 124             Some(local) => {
 125                 // Lazily initialize the local task's logger
 126                 match (*local).logger {
 127                     // Use the available logger if we have one
 128                     Some(ref mut logger) => { logger.log(args); }
 129                     None => {
 130                         let mut logger = StdErrLogger::new();
 131                         logger.log(args);
 132                         (*local).logger = Some(logger);
 133                     }
 134                 }
 135             }
 136             // If there's no local task, then always log to stderr
 137             None => {
 138                 let mut logger = StdErrLogger::new();
 139                 logger.log(args);
 140             }
 141         }
 142     }
 143 }