Google Git
Sign in
fuchsia / third_party / rust-mirrors / rustyline / refs/heads/upstream/gh-pages / . / log / index.html
blob: 244676d8c9e846bb912c8b636f0005f25e7ecd91 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<meta name="description" content="API documentation for the Rust `log` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, log">
<title>log - Rust</title>
<link rel="stylesheet" type="text/css" href="../normalize.css">
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../main.css">
<link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico">
</head>
<body class="rustdoc mod">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<a href='../log/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a>
<p class='location'>Crate log</p><div class="block items"><ul><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'log', ty: 'mod', relpath: '../'};</script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>log</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../src/log/lib.rs.html#11-1040' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>A lightweight logging facade.</p>
<p>The <code>log</code> crate 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.</p>
<p>If no logging implementation is selected, the facade falls back to a &quot;noop&quot;
implementation that ignores all log messages. The overhead in this case
is very small - just an integer load, comparison and jump.</p>
<p>A log request consists of a <em>target</em>, a <em>level</em>, and a <em>body</em>. 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.</p>
<h1 id='use' class='section-header'><a href='#use'>Use</a></h1>
<h2 id='in-libraries' class='section-header'><a href='#in-libraries'>In libraries</a></h2>
<p>Libraries should link only to the <code>log</code> crate, and use the provided
macros to log whatever information will be useful to downstream consumers.</p>
<h3 id='examples' class='section-header'><a href='#examples'>Examples</a></h3>
<pre class="rust rust-example-rendered">
<span class="attribute">#[<span class="ident">macro_use</span>]</span>
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">shave_the_yak</span>(<span class="ident">yak</span>: <span class="kw-2">&amp;</span><span class="ident">Yak</span>) {
<span class="macro">info</span><span class="macro">!</span>(<span class="ident">target</span>: <span class="string">&quot;yak_events&quot;</span>, <span class="string">&quot;Commencing yak shaving for {:?}&quot;</span>, <span class="ident">yak</span>);
<span class="kw">loop</span> {
<span class="kw">match</span> <span class="ident">find_a_razor</span>() {
<span class="prelude-val">Ok</span>(<span class="ident">razor</span>) <span class="op">=&gt;</span> {
<span class="macro">info</span><span class="macro">!</span>(<span class="string">&quot;Razor located: {}&quot;</span>, <span class="ident">razor</span>);
<span class="ident">yak</span>.<span class="ident">shave</span>(<span class="ident">razor</span>);
<span class="kw">break</span>;
}
<span class="prelude-val">Err</span>(<span class="ident">err</span>) <span class="op">=&gt;</span> {
<span class="macro">warn</span><span class="macro">!</span>(<span class="string">&quot;Unable to locate a razor: {}, retrying&quot;</span>, <span class="ident">err</span>);
}
}
}
}</pre>
<h2 id='in-executables' class='section-header'><a href='#in-executables'>In executables</a></h2>
<p>Executables should choose 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.</p>
<p>The executable itself may use the <code>log</code> crate to log as well.</p>
<h3 id='warning' class='section-header'><a href='#warning'>Warning</a></h3>
<p>The logging system may only be initialized once.</p>
<h3 id='examples-1' class='section-header'><a href='#examples-1'>Examples</a></h3>
<pre class="rust rust-example-rendered">
<span class="attribute">#[<span class="ident">macro_use</span>]</span>
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">env_logger</span>;
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="comment">// Select env_logger, one possible logger implementation</span>
<span class="comment">// (see https://doc.rust-lang.org/log/env_logger/index.html)</span>
<span class="ident">env_logger</span>::<span class="ident">init</span>().<span class="ident">unwrap</span>();
<span class="macro">info</span><span class="macro">!</span>(<span class="string">&quot;starting up&quot;</span>);
<span class="macro">error</span><span class="macro">!</span>(<span class="string">&quot;error: {}&quot;</span>, <span class="number">404</span>);
<span class="comment">// ...</span>
}</pre>
<h1 id='logger-implementations' class='section-header'><a href='#logger-implementations'>Logger implementations</a></h1>
<p>Loggers implement the <a href="trait.Log.html"><code>Log</code></a> trait. Here&#39;s a very basic example that simply
logs all messages at the <a href="enum.LogLevel.html"><code>Error</code></a>, <a href="enum.LogLevel.html"><code>Warn</code></a> or
<a href="enum.LogLevel.html"><code>Info</code></a> levels to stdout:</p>
<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">use</span> <span class="ident">log</span>::{<span class="ident">LogRecord</span>, <span class="ident">LogLevel</span>, <span class="ident">LogMetadata</span>};
<span class="kw">struct</span> <span class="ident">SimpleLogger</span>;
<span class="kw">impl</span> <span class="ident">log</span>::<span class="ident">Log</span> <span class="kw">for</span> <span class="ident">SimpleLogger</span> {
<span class="kw">fn</span> <span class="ident">enabled</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">metadata</span>: <span class="kw-2">&amp;</span><span class="ident">LogMetadata</span>) <span class="op">-&gt;</span> <span class="ident">bool</span> {
<span class="ident">metadata</span>.<span class="ident">level</span>() <span class="op">&lt;=</span> <span class="ident">LogLevel</span>::<span class="ident">Info</span>
}
<span class="kw">fn</span> <span class="ident">log</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">record</span>: <span class="kw-2">&amp;</span><span class="ident">LogRecord</span>) {
<span class="kw">if</span> <span class="self">self</span>.<span class="ident">enabled</span>(<span class="ident">record</span>.<span class="ident">metadata</span>()) {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;{} - {}&quot;</span>, <span class="ident">record</span>.<span class="ident">level</span>(), <span class="ident">record</span>.<span class="ident">args</span>());
}
}
}
</pre>
<p>Loggers are installed by calling the <a href="fn.set_logger.html"><code>set_logger</code></a> function. It takes a
closure which is provided a <a href="struct.MaxLogLevelFilter.html"><code>MaxLogLevelFilter</code></a> token and returns a
<a href="trait.Log.html"><code>Log</code></a> trait object. The <a href="struct.MaxLogLevelFilter.html"><code>MaxLogLevelFilter</code></a> 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&#39;ll want to set the maximum log level to
<a href="enum.LogLevel.html"><code>Info</code></a>, since we ignore any <a href="enum.LogLevel.html"><code>Debug</code></a> or
<a href="enum.LogLevel.html"><code>Trace</code></a> level log messages. A logging framework should
provide a function that wraps a call to <a href="fn.set_logger.html"><code>set_logger</code></a>, handling
initialization of the logger:</p>
<pre class="rust rust-example-rendered">
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">init</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">SetLoggerError</span><span class="op">&gt;</span> {
<span class="ident">log</span>::<span class="ident">set_logger</span>(<span class="op">|</span><span class="ident">max_log_level</span><span class="op">|</span> {
<span class="ident">max_log_level</span>.<span class="ident">set</span>(<span class="ident">LogLevelFilter</span>::<span class="ident">Info</span>);
<span class="ident">Box</span>::<span class="ident">new</span>(<span class="ident">SimpleLogger</span>)
})
}</pre>
<h1 id='use-with-no_std' class='section-header'><a href='#use-with-no_std'>Use with <code>no_std</code></a></h1>
<p>To use the <code>log</code> crate without depending on <code>libstd</code>, you need to specify
<code>default-features = false</code> when specifying the dependency in <code>Cargo.toml</code>.
This makes no difference to libraries using <code>log</code> since the logging API
remains the same. However executables will need to use the <a href="fn.set_logger_raw.html"><code>set_logger_raw</code></a>
function to initialize a logger and the <a href="fn.shutdown_logger_raw.html"><code>shutdown_logger_raw</code></a> function to
shut down the global logger before exiting:</p>
<pre class="rust rust-example-rendered">
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">init</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">SetLoggerError</span><span class="op">&gt;</span> {
<span class="kw">unsafe</span> {
<span class="ident">log</span>::<span class="ident">set_logger_raw</span>(<span class="op">|</span><span class="ident">max_log_level</span><span class="op">|</span> {
<span class="kw">static</span> <span class="ident">LOGGER</span>: <span class="ident">SimpleLogger</span> <span class="op">=</span> <span class="ident">SimpleLogger</span>;
<span class="ident">max_log_level</span>.<span class="ident">set</span>(<span class="ident">LogLevelFilter</span>::<span class="ident">Info</span>);
<span class="kw-2">&amp;</span><span class="ident">SimpleLogger</span>
})
}
}
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">shutdown</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">ShutdownLoggerError</span><span class="op">&gt;</span> {
<span class="ident">log</span>::<span class="ident">shutdown_logger_raw</span>().<span class="ident">map</span>(<span class="op">|</span><span class="ident">logger</span><span class="op">|</span> {
<span class="kw">let</span> <span class="ident">logger</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="kw-2">&amp;</span><span class="kw-2">*</span>(<span class="ident">logger</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">SimpleLogger</span>) };
<span class="ident">logger</span>.<span class="ident">flush</span>();
})
}</pre>
</div><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
<tr class=' module-item'>
<td><a class="macro" href="macro.debug.html"
title='macro log::debug'>debug</a></td>
<td class='docblock-short'>
<p>Logs a message at the debug level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.error.html"
title='macro log::error'>error</a></td>
<td class='docblock-short'>
<p>Logs a message at the error level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.info.html"
title='macro log::info'>info</a></td>
<td class='docblock-short'>
<p>Logs a message at the info level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.log.html"
title='macro log::log'>log</a></td>
<td class='docblock-short'>
<p>The standard logging macro.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.log_enabled.html"
title='macro log::log_enabled'>log_enabled</a></td>
<td class='docblock-short'>
<p>Determines if a message logged at the specified level in that module will
be logged.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.trace.html"
title='macro log::trace'>trace</a></td>
<td class='docblock-short'>
<p>Logs a message at the trace level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.warn.html"
title='macro log::warn'>warn</a></td>
<td class='docblock-short'>
<p>Logs a message at the warn level.</p>
</td>
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogLocation.html"
title='struct log::LogLocation'>LogLocation</a></td>
<td class='docblock-short'>
<p>The location of a log message.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogMetadata.html"
title='struct log::LogMetadata'>LogMetadata</a></td>
<td class='docblock-short'>
<p>Metadata about a log message.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogRecord.html"
title='struct log::LogRecord'>LogRecord</a></td>
<td class='docblock-short'>
<p>The &quot;payload&quot; of a log message. This structure is primarily used as a
parameter in the <a href="trait.Log.html"><code>log</code></a> method of the <a href="trait.Log.html"><code>Log</code></a> trait.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.MaxLogLevelFilter.html"
title='struct log::MaxLogLevelFilter'>MaxLogLevelFilter</a></td>
<td class='docblock-short'>
<p>A token providing read and write access to the global maximum log level
filter.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.SetLoggerError.html"
title='struct log::SetLoggerError'>SetLoggerError</a></td>
<td class='docblock-short'>
<p>The type returned by <code>set_logger</code> if <code>set_logger</code> has already been called.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.ShutdownLoggerError.html"
title='struct log::ShutdownLoggerError'>ShutdownLoggerError</a></td>
<td class='docblock-short'>
<p>The type returned by <code>shutdown_logger_raw</code> if <code>shutdown_logger_raw</code> has
already been called or if <code>set_logger_raw</code> has not been called yet.</p>
</td>
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table>
<tr class=' module-item'>
<td><a class="enum" href="enum.LogLevel.html"
title='enum log::LogLevel'>LogLevel</a></td>
<td class='docblock-short'>
<p>An enum representing the available verbosity levels of the logging framework.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="enum" href="enum.LogLevelFilter.html"
title='enum log::LogLevelFilter'>LogLevelFilter</a></td>
<td class='docblock-short'>
<p>An enum representing the available verbosity level filters of the logging
framework.</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class="trait" href="trait.Log.html"
title='trait log::Log'>Log</a></td>
<td class='docblock-short'>
<p>A trait encapsulating the operations required of a logger</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="fn" href="fn.max_log_level.html"
title='fn log::max_log_level'>max_log_level</a></td>
<td class='docblock-short'>
<p>Returns the current maximum log level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.set_logger.html"
title='fn log::set_logger'>set_logger</a></td>
<td class='docblock-short'>
<p>Sets the global logger.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.set_logger_raw.html"
title='fn log::set_logger_raw'>set_logger_raw</a><a title='unsafe function' href='#'><sup>⚠</sup></a></td>
<td class='docblock-short'>
<p>Sets the global logger from a raw pointer.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.shutdown_logger.html"
title='fn log::shutdown_logger'>shutdown_logger</a></td>
<td class='docblock-short'>
<p>Shuts down the global logger.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.shutdown_logger_raw.html"
title='fn log::shutdown_logger_raw'>shutdown_logger_raw</a></td>
<td class='docblock-short'>
<p>Shuts down the global logger.</p>
</td>
</tr></table></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>&larrb;</dt>
<dd>Move up in search results</dd>
<dt>&rarrb;</dt>
<dd>Move down in search results</dd>
<dt>&#9166;</dt>
<dd>Go to active search result</dd>
<dt>+</dt>
<dd>Collapse/expand all sections</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "log";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>