<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>Logger – Logger v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/logger/v1.7/Logger.html" />
<script src="dist/sidebar_items-17aeec0e2f.js"></script>
</head>
<body data-type="modules">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
Logger </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="Logger" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">Logger v1.7.2</small>
Logger
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>A logger for Elixir applications.</p>
<p>It includes many features:</p>
<ul>
<li><p>Provides debug, info, warn, and error levels.</p>
</li>
<li><p>Supports multiple backends which are automatically
supervised when plugged into <a href="Logger.html#content"><code class="inline">Logger</code></a>.</p>
</li>
<li><p>Formats and truncates messages on the client
to avoid clogging <a href="Logger.html#content"><code class="inline">Logger</code></a> backends.</p>
</li>
<li><p>Alternates between sync and async modes to remain
performant when required but also apply backpressure
when under stress.</p>
</li>
<li><p>Plugs into Erlang’s <a href="http://erlang.org/doc/man/logger.html"><code class="inline">:logger</code></a>
(from Erlang/OTP 21) to convert terms to Elixir syntax or wraps
Erlang’s <a href="http://erlang.org/doc/man/error_logger.html"><code class="inline">:error_logger</code></a>
in earlier Erlang/OTP versions to prevent it from overflowing.</p>
</li>
</ul>
<p>Logging is useful for tracking when an event of interest happens in your
system. For example, it may be helpful to log whenever a user is deleted.</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">delete_user</span><span class="p" data-group-id="2883353951-1">(</span><span class="n">user</span><span class="p" data-group-id="2883353951-1">)</span><span class="w"> </span><span class="k" data-group-id="2883353951-2">do</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">info</span><span class="w"> </span><span class="s">"Deleting user from the system: </span><span class="si" data-group-id="2883353951-3">#{</span><span class="n">inspect</span><span class="p" data-group-id="2883353951-4">(</span><span class="n">user</span><span class="p" data-group-id="2883353951-4">)</span><span class="si" data-group-id="2883353951-3">}</span><span class="s">"</span><span class="w">
</span><span class="c1"># ...</span><span class="w">
</span><span class="k" data-group-id="2883353951-2">end</span></code></pre>
<p>The <a href="Logger.html#info/2"><code class="inline">Logger.info/2</code></a> macro emits the provided message at the <code class="inline">:info</code>
level. Note the arguments given to <a href="#info/2"><code class="inline">info/2</code></a> will only be evaluated
if a message is logged. For instance, if the Logger level is
set to <code class="inline">:warn</code>, <code class="inline">:info</code> messages are never logged and therefore the
arguments given above won’t even be executed.</p>
<p>There are additional macros for other levels.</p>
<p>Logger also allows log commands to be removed altogether via the
<code class="inline">:compile_time_purge_matching</code> option (see below).</p>
<p>For dynamically logging messages, see <a href="#bare_log/3"><code class="inline">bare_log/3</code></a>. But note that
<a href="#bare_log/3"><code class="inline">bare_log/3</code></a> always evaluates its arguments (unless the argument
is an anonymous function).</p>
<h2 id="module-levels" class="section-heading">
<a href="#module-levels" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Levels
</h2>
<p>The supported levels are:</p>
<ul>
<li><code class="inline">:debug</code> - for debug-related messages
</li>
<li><code class="inline">:info</code> - for information of any kind
</li>
<li><code class="inline">:warn</code> - for warnings
</li>
<li><code class="inline">:error</code> - for errors
</li>
</ul>
<h2 id="module-configuration" class="section-heading">
<a href="#module-configuration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Configuration
</h2>
<p><a href="Logger.html#content"><code class="inline">Logger</code></a> supports a wide range of configurations.</p>
<p>This configuration is split in three categories:</p>
<ul>
<li><p>Application configuration - must be set before the <code class="inline">:logger</code>
application is started</p>
</li>
<li><p>Runtime configuration - can be set before the <code class="inline">:logger</code>
application is started, but may be changed during runtime</p>
</li>
<li><p>Erlang configuration - options that handle integration with
Erlang’s logging facilities</p>
</li>
</ul>
<h3 id="module-application-configuration" class="section-heading">
<a href="#module-application-configuration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Application configuration
</h3>
<p>The following configuration must be set via config files (such as
<code class="inline">config/config.exs</code>) before the <code class="inline">:logger</code> application is started.</p>
<ul>
<li><p><code class="inline">:backends</code> - the backends to be used. Defaults to <code class="inline">[:console]</code>.
See the “Backends” section for more information.</p>
</li>
<li><p><code class="inline">:compile_time_application</code> - sets the <code class="inline">:application</code> metadata value
to the configured value at compilation time. This configuration is
usually only useful for build tools to automatically add the
application to the metadata for <a href="Logger.html#debug/2"><code class="inline">Logger.debug/2</code></a>, <a href="Logger.html#info/2"><code class="inline">Logger.info/2</code></a>, etc.
style of calls.</p>
</li>
<li><p><code class="inline">:compile_time_purge_matching</code> - purges <em>at compilation time</em> all calls
that match the given conditions. This means that <a href="Logger.html#content"><code class="inline">Logger</code></a> calls with
level lower than this option will be completely removed at compile time,
accruing no overhead at runtime. This configuration expects a list of
keyword lists. Each keyword list contains a metadata key and the matching
value that should be purged. A special key named <code class="inline">:level_lower_than</code> can
be used to purge all messages with a lower logger level. Remember that
if you want to purge log calls from a dependency, the dependency must be
recompiled.</p>
</li>
</ul>
<p>For example, to configure the <code class="inline">:backends</code> and purge all calls that happen
at compile time with level lower than <code class="inline">:info</code> in a <code class="inline">config/config.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w">
</span><span class="ss">backends</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4550486263-1">[</span><span class="ss">:console</span><span class="p" data-group-id="4550486263-1">]</span><span class="p">,</span><span class="w">
</span><span class="ss">compile_time_purge_matching</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4550486263-2">[</span><span class="w">
</span><span class="p" data-group-id="4550486263-3">[</span><span class="ss">level_lower_than</span><span class="p">:</span><span class="w"> </span><span class="ss">:info</span><span class="p" data-group-id="4550486263-3">]</span><span class="w">
</span><span class="p" data-group-id="4550486263-2">]</span></code></pre>
<p>If you want to purge all log calls from an application named <code class="inline">:foo</code> and only
keep errors from <code class="inline">Bar.foo/3</code>, you can set up two different matches:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w">
</span><span class="ss">compile_time_purge_matching</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="2918699079-1">[</span><span class="w">
</span><span class="p" data-group-id="2918699079-2">[</span><span class="ss">application</span><span class="p">:</span><span class="w"> </span><span class="ss">:foo</span><span class="p" data-group-id="2918699079-2">]</span><span class="p">,</span><span class="w">
</span><span class="p" data-group-id="2918699079-3">[</span><span class="ss">module</span><span class="p">:</span><span class="w"> </span><span class="nc">Bar</span><span class="p">,</span><span class="w"> </span><span class="ss">function</span><span class="p">:</span><span class="w"> </span><span class="s">"foo/3"</span><span class="p">,</span><span class="w"> </span><span class="ss">level_lower_than</span><span class="p">:</span><span class="w"> </span><span class="ss">:error</span><span class="p" data-group-id="2918699079-3">]</span><span class="w">
</span><span class="p" data-group-id="2918699079-1">]</span></code></pre>
<h3 id="module-runtime-configuration" class="section-heading">
<a href="#module-runtime-configuration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Runtime Configuration
</h3>
<p>All configuration below can be set via config files (such as
<code class="inline">config/config.exs</code>) but also changed dynamically during runtime via
<a href="Logger.html#configure/1"><code class="inline">Logger.configure/1</code></a>.</p>
<ul>
<li><p><code class="inline">:level</code> - the logging level. Attempting to log any message
with severity less than the configured level will simply
cause the message to be ignored. Keep in mind that each backend
may have its specific level, too.</p>
</li>
<li><p><code class="inline">:utc_log</code> - when <code class="inline">true</code>, uses UTC in logs. By default it uses
local time (i.e., it defaults to <code class="inline">false</code>).</p>
</li>
<li><p><code class="inline">:truncate</code> - the maximum message size to be logged (in bytes).
Defaults to 8192 bytes. Note this configuration is approximate.
Truncated messages will have <code class="inline">" (truncated)"</code> at the end.
The atom <code class="inline">:infinity</code> can be passed to disable this behavior.</p>
</li>
<li><p><code class="inline">:sync_threshold</code> - if the <a href="Logger.html#content"><code class="inline">Logger</code></a> manager has more than
<code class="inline">:sync_threshold</code> messages in its queue, <a href="Logger.html#content"><code class="inline">Logger</code></a> will change
to <em>sync mode</em>, to apply backpressure to the clients.
<a href="Logger.html#content"><code class="inline">Logger</code></a> will return to <em>async mode</em> once the number of messages
in the queue is reduced to <code class="inline">sync_threshold * 0.75</code> messages.
Defaults to 20 messages. <code class="inline">:sync_threshold</code> can be set to <code class="inline">0</code> to force <em>sync mode</em>.</p>
</li>
<li><p><code class="inline">:discard_threshold</code> - if the <a href="Logger.html#content"><code class="inline">Logger</code></a> manager has more than
<code class="inline">:discard_threshold</code> messages in its queue, <a href="Logger.html#content"><code class="inline">Logger</code></a> will change
to <em>discard mode</em> and messages will be discarded directly in the
clients. <a href="Logger.html#content"><code class="inline">Logger</code></a> will return to <em>sync mode</em> once the number of
messages in the queue is reduced to <code class="inline">discard_threshold * 0.75</code>
messages. Defaults to 500 messages.</p>
</li>
<li><p><code class="inline">:translator_inspect_opts</code> - when translating OTP reports and
errors, the last message and state must be inspected in the
error reports. This configuration allow developers to change
how much and how the data should be inspected.</p>
</li>
</ul>
<p>For example, to configure the <code class="inline">:level</code> and <code class="inline">:truncate</code> options in a
<code class="inline">config/config.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w">
</span><span class="ss">level</span><span class="p">:</span><span class="w"> </span><span class="ss">:warn</span><span class="p">,</span><span class="w">
</span><span class="ss">truncate</span><span class="p">:</span><span class="w"> </span><span class="mi">4096</span></code></pre>
<h3 id="module-error-logger-configuration" class="section-heading">
<a href="#module-error-logger-configuration" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Error logger configuration
</h3>
<p>The following configuration applies to <a href="Logger.html#content"><code class="inline">Logger</code></a>’s wrapper around
Erlang’s logging functionalities. All the configurations below must
be set before the <code class="inline">:logger</code> application starts.</p>
<ul>
<li><p><code class="inline">:handle_otp_reports</code> - redirects OTP reports to <a href="Logger.html#content"><code class="inline">Logger</code></a> so
they are formatted in Elixir terms. This effectively disables
Erlang standard logger. Defaults to <code class="inline">true</code>.</p>
</li>
<li><p><code class="inline">:handle_sasl_reports</code> - redirects supervisor, crash and
progress reports to <a href="Logger.html#content"><code class="inline">Logger</code></a> so they are formatted in Elixir
terms. Your application must guarantee <code class="inline">:sasl</code> is started before
<code class="inline">:logger</code>. This means you may see some initial reports written
in Erlang syntax until the Logger application kicks in.
Defaults to <code class="inline">false</code>.</p>
</li>
</ul>
<p>From Erlang/OTP 21, <code class="inline">:handle_sasl_reports</code> only has an effect if
<code class="inline">:handle_otp_reports</code> is true.</p>
<p>The following configurations apply only for Erlang/OTP 20 and earlier:</p>
<ul>
<li><code class="inline">:discard_threshold_for_error_logger</code> - if <code class="inline">:error_logger</code> has more than
<code class="inline">discard_threshold</code> messages in its inbox, messages will be dropped
until the message queue goes down to <code class="inline">discard_threshold * 0.75</code>
entries. The threshold will be checked once again after 10% of threshold
messages are processed, to avoid messages from being constantly dropped.
For example, if the threshold is 500 (the default) and the inbox has
600 messages, 225 messages will dropped, bringing the inbox down to
375 (0.75 <em> threshold) entries and 50 (0.1 </em> threshold) messages will
be processed before the threshold is checked once again.
</li>
</ul>
<p>For example, to configure <a href="Logger.html#content"><code class="inline">Logger</code></a> to redirect all Erlang messages using a
<code class="inline">config/config.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w">
</span><span class="ss">handle_otp_reports</span><span class="p">:</span><span class="w"> </span><span class="no">true</span><span class="p">,</span><span class="w">
</span><span class="ss">handle_sasl_reports</span><span class="p">:</span><span class="w"> </span><span class="no">true</span></code></pre>
<p>Furthermore, <a href="Logger.html#content"><code class="inline">Logger</code></a> allows messages sent by Erlang to be translated
into an Elixir format via translators. Translators can be added at any
time with the <a href="#add_translator/1"><code class="inline">add_translator/1</code></a> and <a href="#remove_translator/1"><code class="inline">remove_translator/1</code></a> APIs. Check
<a href="Logger.Translator.html"><code class="inline">Logger.Translator</code></a> for more information.</p>
<h2 id="module-backends" class="section-heading">
<a href="#module-backends" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Backends
</h2>
<p><a href="Logger.html#content"><code class="inline">Logger</code></a> supports different backends where log messages are written to.</p>
<p>The available backends by default are:</p>
<ul>
<li><code class="inline">:console</code> - logs messages to the console (enabled by default)
</li>
</ul>
<p>Developers may also implement their own backends, an option that
is explored in more detail below.</p>
<p>The initial backends are loaded via the <code class="inline">:backends</code> configuration,
which must be set before the <code class="inline">:logger</code> application is started.</p>
<h3 id="module-console-backend" class="section-heading">
<a href="#module-console-backend" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Console backend
</h3>
<p>The console backend logs messages by printing them to the console. It supports
the following options:</p>
<ul>
<li><p><code class="inline">:level</code> - the level to be logged by this backend.
Note that messages are filtered by the general
<code class="inline">:level</code> configuration for the <code class="inline">:logger</code> application first.</p>
</li>
<li><p><code class="inline">:format</code> - the format message used to print logs.
Defaults to: <code class="inline">"\n$time $metadata[$level] $levelpad$message\n"</code>.
It may also be a <code class="inline">{module, function}</code> tuple that is invoked
with the log level, the message, the current timestamp and
the metadata.</p>
</li>
<li><p><code class="inline">:metadata</code> - the metadata to be printed by <code class="inline">$metadata</code>.
Defaults to an empty list (no metadata).
Setting <code class="inline">:metadata</code> to <code class="inline">:all</code> prints all metadata. See
the “Metadata” section for more information.</p>
</li>
<li><p><code class="inline">:colors</code> - a keyword list of coloring options.</p>
</li>
<li><p><code class="inline">:device</code> - the device to log error messages to. Defaults to
<code class="inline">:user</code> but can be changed to something else such as <code class="inline">:standard_error</code>.</p>
</li>
<li><p><code class="inline">:max_buffer</code> - maximum events to buffer while waiting
for a confirmation from the IO device (default: 32).
Once the buffer is full, the backend will block until
a confirmation is received.</p>
</li>
</ul>
<p>The supported keys in the <code class="inline">:colors</code> keyword list are:</p>
<ul>
<li><p><code class="inline">:enabled</code> - boolean value that allows for switching the
coloring on and off. Defaults to: <a href="https://hexdocs.pm/elixir/IO.ANSI.html#enabled?/0"><code class="inline">IO.ANSI.enabled?/0</code></a></p>
</li>
<li><p><code class="inline">:debug</code> - color for debug messages. Defaults to: <code class="inline">:cyan</code></p>
</li>
<li><p><code class="inline">:info</code> - color for info messages. Defaults to: <code class="inline">:normal</code></p>
</li>
<li><p><code class="inline">:warn</code> - color for warn messages. Defaults to: <code class="inline">:yellow</code></p>
</li>
<li><p><code class="inline">:error</code> - color for error messages. Defaults to: <code class="inline">:red</code></p>
</li>
</ul>
<p>See the <a href="https://hexdocs.pm/elixir/IO.ANSI.html"><code class="inline">IO.ANSI</code></a> module for a list of colors and attributes.</p>
<p>Here is an example of how to configure the <code class="inline">:console</code> backend in a
<code class="inline">config/config.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w"> </span><span class="ss">:console</span><span class="p">,</span><span class="w">
</span><span class="ss">format</span><span class="p">:</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">$time $metadata[$level] $levelpad$message</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span><span class="w">
</span><span class="ss">metadata</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="7861362907-1">[</span><span class="ss">:user_id</span><span class="p" data-group-id="7861362907-1">]</span></code></pre>
<h2 id="module-metadata" class="section-heading">
<a href="#module-metadata" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Metadata
</h2>
<p>In addition to the keys provided by the user via <a href="Logger.html#metadata/1"><code class="inline">Logger.metadata/1</code></a>,
the following extra keys are available to the <code class="inline">:metadata</code> list:</p>
<ul>
<li><p><code class="inline">:application</code> - the current application</p>
</li>
<li><p><code class="inline">:module</code> - the current module</p>
</li>
<li><p><code class="inline">:function</code> - the current function</p>
</li>
<li><p><code class="inline">:file</code> - the current file</p>
</li>
<li><p><code class="inline">:line</code> - the current line</p>
</li>
<li><p><code class="inline">:pid</code> - the current process identifier</p>
</li>
<li><p><code class="inline">:crash_reason</code> - a two-element tuple with the throw/error/exit reason
as first argument and the stacktrace as second. A throw will always be
<code class="inline">{:nocatch, term}</code>. An error is always an <a href="https://hexdocs.pm/elixir/Exception.html"><code class="inline">Exception</code></a> struct. All other
entries are exits. The console backend ignores this metadata by default
but it can be useful to other backends, such as the ones that report
errors to third-party services</p>
</li>
<li><p><code class="inline">:initial_call</code> - the initial call that started the process</p>
</li>
<li><p><code class="inline">:registered_name</code> - the process registered name as an atom</p>
</li>
</ul>
<p>Note that all metadata is optional and may not always be available.
The <code class="inline">:module</code>, <code class="inline">:function</code>, <code class="inline">:line</code>, and similar metadata are automatically
included when using <a href="Logger.html#content"><code class="inline">Logger</code></a> macros. <a href="Logger.html#bare_log/3"><code class="inline">Logger.bare_log/3</code></a> does not include
any metadata beyond the <code class="inline">:pid</code> by default. Other metadata, such as
<code class="inline">:crash_reason</code>, <code class="inline">:initial_call</code>, and <code class="inline">:registered_name</code> are extracted
from Erlang/OTP crash reports and available only in those cases.</p>
<h3 id="module-custom-formatting" class="section-heading">
<a href="#module-custom-formatting" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Custom formatting
</h3>
<p>The console backend allows you to customize the format of your log messages
with the <code class="inline">:format</code> option.</p>
<p>You may set <code class="inline">:format</code> to either a string or a <code class="inline">{module, function}</code> tuple if
you wish to provide your own format function. Here is an example of how to
configure the <code class="inline">:console</code> backend in a <code class="inline">config/config.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:logger</span><span class="p">,</span><span class="w"> </span><span class="ss">:console</span><span class="p">,</span><span class="w">
</span><span class="ss">format</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="8814775781-1">{</span><span class="nc">MyConsoleLogger</span><span class="p">,</span><span class="w"> </span><span class="ss">:format</span><span class="p" data-group-id="8814775781-1">}</span></code></pre>
<p>And here is an example of how you can define <code class="inline">MyConsoleLogger.format/4</code> from the
above configuration:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyConsoleLogger</span><span class="w"> </span><span class="k" data-group-id="9785960523-1">do</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">format</span><span class="p" data-group-id="9785960523-2">(</span><span class="n">level</span><span class="p">,</span><span class="w"> </span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="n">timestamp</span><span class="p">,</span><span class="w"> </span><span class="n">metadata</span><span class="p" data-group-id="9785960523-2">)</span><span class="w"> </span><span class="k" data-group-id="9785960523-3">do</span><span class="w">
</span><span class="c1"># Custom formatting logic...</span><span class="w">
</span><span class="k" data-group-id="9785960523-3">end</span><span class="w">
</span><span class="k" data-group-id="9785960523-1">end</span></code></pre>
<p>It is extremely important that <strong>the formatting function does not fail</strong>, as
it will bring that particular logger instance down, causing your system to
temporarily lose messages. If necessary, wrap the function in a <code class="inline">rescue</code> and
log a default message instead:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyConsoleLogger</span><span class="w"> </span><span class="k" data-group-id="6658528903-1">do</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">format</span><span class="p" data-group-id="6658528903-2">(</span><span class="n">level</span><span class="p">,</span><span class="w"> </span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="n">timestamp</span><span class="p">,</span><span class="w"> </span><span class="n">metadata</span><span class="p" data-group-id="6658528903-2">)</span><span class="w"> </span><span class="k" data-group-id="6658528903-3">do</span><span class="w">
</span><span class="c1"># Custom formatting logic...</span><span class="w">
</span><span class="k" data-group-id="6658528903-3">rescue</span><span class="w">
</span><span class="bp">_</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="s">"could not format: </span><span class="si" data-group-id="6658528903-4">#{</span><span class="n">inspect</span><span class="p" data-group-id="6658528903-5">(</span><span class="p" data-group-id="6658528903-6">{</span><span class="n">level</span><span class="p">,</span><span class="w"> </span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="n">metadata</span><span class="p" data-group-id="6658528903-6">}</span><span class="si">}</span><span class="s">)"</span><span class="w">
</span><span class="k">end</span><span class="w">
</span><span class="k">end</span></code></pre>
<p>The <code class="inline">{module, function}</code> will be invoked with four arguments:</p>
<ul>
<li>the log level: an atom
</li>
<li>the message: this is usually chardata, but in some cases it may not be.
Since the formatting function should <em>never</em> fail, you need to prepare for
the message being anything (and do something like the <code class="inline">rescue</code> in the example
above)
</li>
<li>the current timestamp: a term of type <a href="Logger.Formatter.html#t:time/0"><code class="inline">Logger.Formatter.time/0</code></a>
</li>
<li>the medatata: a keyword list
</li>
</ul>
<p>You can read more about formatting in <a href="Logger.Formatter.html"><code class="inline">Logger.Formatter</code></a>.</p>
<h3 id="module-custom-backends" class="section-heading">
<a href="#module-custom-backends" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Custom backends
</h3>
<p>Any developer can create their own <a href="Logger.html#content"><code class="inline">Logger</code></a> backend.
Since <a href="Logger.html#content"><code class="inline">Logger</code></a> is an event manager powered by <code class="inline">:gen_event</code>,
writing a new backend is a matter of creating an event
handler, as described in the <a href="http://erlang.org/doc/man/gen_event.html"><code class="inline">:gen_event</code></a>
documentation.</p>
<p>From now on, we will be using the term “event handler” to refer
to your custom backend, as we head into implementation details.</p>
<p>Once the <code class="inline">:logger</code> application starts, it installs all event handlers listed under
the <code class="inline">:backends</code> configuration into the <a href="Logger.html#content"><code class="inline">Logger</code></a> event manager. The event
manager and all added event handlers are automatically supervised by <a href="Logger.html#content"><code class="inline">Logger</code></a>.</p>
<p>Once initialized, the handler should be designed to handle events
in the following format:</p>
<pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="3613245383-1">{</span><span class="n">level</span><span class="p">,</span><span class="w"> </span><span class="n">group_leader</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="3613245383-2">{</span><span class="nc">Logger</span><span class="p">,</span><span class="w"> </span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="n">timestamp</span><span class="p">,</span><span class="w"> </span><span class="n">metadata</span><span class="p" data-group-id="3613245383-2">}</span><span class="p" data-group-id="3613245383-1">}</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="ss">:flush</span></code></pre>
<p>where:</p>
<ul>
<li><code class="inline">level</code> is one of <code class="inline">:debug</code>, <code class="inline">:info</code>, <code class="inline">:warn</code>, or <code class="inline">:error</code>, as previously
described
</li>
<li><code class="inline">group_leader</code> is the group leader of the process which logged the message
</li>
<li><p><code class="inline">{Logger, message, timestamp, metadata}</code> is a tuple containing information
about the logged message:</p>
<ul>
<li>the first element is always the atom <a href="Logger.html#content"><code class="inline">Logger</code></a>
</li>
<li><code class="inline">message</code> is the actual message (as chardata)
</li>
<li><code class="inline">timestamp</code> is the timestamp for when the message was logged, as a
<code class="inline">{{year, month, day}, {hour, minute, second, millisecond}}</code> tuple
</li>
<li><code class="inline">metadata</code> is a keyword list of metadata used when logging the message
</li>
</ul>
</li>
</ul>
<p>It is recommended that handlers ignore messages where
the group leader is in a different node than the one where
the handler is installed. For example:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">handle_event</span><span class="p" data-group-id="0378718142-1">(</span><span class="p" data-group-id="0378718142-2">{</span><span class="c">_level</span><span class="p">,</span><span class="w"> </span><span class="n">gl</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="0378718142-3">{</span><span class="nc">Logger</span><span class="p">,</span><span class="w"> </span><span class="bp">_</span><span class="p">,</span><span class="w"> </span><span class="bp">_</span><span class="p">,</span><span class="w"> </span><span class="bp">_</span><span class="p" data-group-id="0378718142-3">}</span><span class="p" data-group-id="0378718142-2">}</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="0378718142-1">)</span><span class="w">
</span><span class="ow">when</span><span class="w"> </span><span class="n">node</span><span class="p" data-group-id="0378718142-4">(</span><span class="n">gl</span><span class="p" data-group-id="0378718142-4">)</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">node</span><span class="p" data-group-id="0378718142-5">(</span><span class="p" data-group-id="0378718142-5">)</span><span class="w"> </span><span class="k" data-group-id="0378718142-6">do</span><span class="w">
</span><span class="p" data-group-id="0378718142-7">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="p" data-group-id="0378718142-7">}</span><span class="w">
</span><span class="k" data-group-id="0378718142-6">end</span></code></pre>
<p>In the case of the event <code class="inline">:flush</code> handlers should flush any pending data. This
event is triggered by <a href="#flush/0"><code class="inline">flush/0</code></a>.</p>
<p>Furthermore, backends can be configured via the
<a href="#configure_backend/2"><code class="inline">configure_backend/2</code></a> function which requires event handlers
to handle calls of the following format:</p>
<pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="2376432063-1">{</span><span class="ss">:configure</span><span class="p">,</span><span class="w"> </span><span class="n">options</span><span class="p" data-group-id="2376432063-1">}</span></code></pre>
<p>where <code class="inline">options</code> is a keyword list. The result of the call is
the result returned by <a href="#configure_backend/2"><code class="inline">configure_backend/2</code></a>. The recommended
return value for successful configuration is <code class="inline">:ok</code>.</p>
<p>It is recommended that backends support at least the following
configuration options:</p>
<ul>
<li><code class="inline">:level</code> - the logging level for that backend
</li>
<li><code class="inline">:format</code> - the logging format for that backend
</li>
<li><code class="inline">:metadata</code> - the metadata to include in that backend
</li>
</ul>
<p>Check the implementation for <code class="inline">Logger.Backends.Console</code>, for
examples on how to handle the recommendations in this section
and how to process the existing options.</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-types summary">
<h2>
<a href="#types">Types</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:backend/0">backend()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:level/0">level()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:message/0">message()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:metadata/0">metadata()</a>
</div>
</div>
</div>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#add_backend/2">add_backend(backend, opts \\ [])</a>
</div>
<div class="summary-synopsis"><p>Adds a new backend</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#add_translator/1">add_translator(translator)</a>
</div>
<div class="summary-synopsis"><p>Adds a new translator</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#bare_log/3">bare_log(level, chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs a message dynamically</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#compare_levels/2">compare_levels(level, level)</a>
</div>
<div class="summary-synopsis"><p>Compares log levels</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#configure/1">configure(options)</a>
</div>
<div class="summary-synopsis"><p>Configures the logger</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#configure_backend/2">configure_backend(backend, options)</a>
</div>
<div class="summary-synopsis"><p>Configures the given backend</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#debug/2">debug(chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs a debug message</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#disable/1">disable(pid)</a>
</div>
<div class="summary-synopsis"><p>Disables logging for the current process</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#enable/1">enable(pid)</a>
</div>
<div class="summary-synopsis"><p>Enables logging for the current process</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#error/2">error(chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs an error message</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#flush/0">flush()</a>
</div>
<div class="summary-synopsis"><p>Flushes the logger</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#info/2">info(chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs an info message</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#level/0">level()</a>
</div>
<div class="summary-synopsis"><p>Retrieves the <a href="Logger.html#content"><code class="inline">Logger</code></a> level</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#log/3">log(level, chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs a message with the given <code class="inline">level</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#metadata/0">metadata()</a>
</div>
<div class="summary-synopsis"><p>Reads the current process metadata</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#metadata/1">metadata(keyword)</a>
</div>
<div class="summary-synopsis"><p>Alters the current process metadata according the given keyword list</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#remove_backend/2">remove_backend(backend, opts \\ [])</a>
</div>
<div class="summary-synopsis"><p>Removes a backend</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#remove_translator/1">remove_translator(translator)</a>
</div>
<div class="summary-synopsis"><p>Removes a translator</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#reset_metadata/1">reset_metadata(keywords \\ [])</a>
</div>
<div class="summary-synopsis"><p>Resets the current process metadata to the given keyword list</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#warn/2">warn(chardata_or_fun, metadata \\ [])</a>
</div>
<div class="summary-synopsis"><p>Logs a warning message</p>
</div>
</div>
</div>
</section>
<section id="types" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#types">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Types
</h1>
<div class="types-list">
<div class="detail" id="t:backend/0">
<div class="detail-header">
<a href="#t:backend/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">backend()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L416" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>backend() :: <a href="http://www.erlang.org/doc/man/gen_event.html#type-handler">:gen_event.handler</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:level/0">
<div class="detail-header">
<a href="#t:level/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">level()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L418" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>level() :: :error | :info | :warn | :debug</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:message/0">
<div class="detail-header">
<a href="#t:message/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">message()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L417" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>message() :: <a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>() | <a href="https://hexdocs.pm/elixir/String.Chars.html#t:t/0">String.Chars.t</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:metadata/0">
<div class="detail-header">
<a href="#t:metadata/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">metadata()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L419" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>metadata() :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Functions
</h1>
<div class="detail" id="add_backend/2">
<span id="add_backend/1"></span>
<div class="detail-header">
<a href="#add_backend/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">add_backend(backend, opts \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L586" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>add_backend(<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()) :: <a href="https://hexdocs.pm/elixir/Supervisor.html#t:on_start_child/0">Supervisor.on_start_child</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Adds a new backend.</p>
<h2 id="add_backend/2-options" class="section-heading">
<a href="#add_backend/2-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<ul>
<li><code class="inline">:flush</code> - when <code class="inline">true</code>, guarantees all messages currently sent
to <a href="Logger.html#content"><code class="inline">Logger</code></a> are processed before the backend is added
</li>
</ul>
</section>
</div>
<div class="detail" id="add_translator/1">
<div class="detail-header">
<a href="#add_translator/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">add_translator(translator)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L622" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>add_translator({<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">module</a>(), function :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()}) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Adds a new translator.</p>
</section>
</div>
<div class="detail" id="bare_log/3">
<span id="bare_log/2"></span>
<div class="detail-header">
<a href="#bare_log/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">bare_log(level, chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L655" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>bare_log(
<a href="#t:level/0">level</a>(),
<a href="#t:message/0">message</a>() | (() -> <a href="#t:message/0">message</a>() | {<a href="#t:message/0">message</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()}),
<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()
) :: :ok | {:error, :noproc} | {:error, <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Logs a message dynamically.</p>
<p>Opposite to <a href="#log/3"><code class="inline">log/3</code></a>, <a href="#debug/2"><code class="inline">debug/2</code></a>, <a href="#info/2"><code class="inline">info/2</code></a>, and friends, the arguments
given to <a href="#bare_log/3"><code class="inline">bare_log/3</code></a> are always evaluated. However, you can pass
anonymous functions to <a href="#bare_log/3"><code class="inline">bare_log/3</code></a> and they will only be evaluated
if there is something to be logged.</p>
</section>
</div>
<div class="detail" id="compare_levels/2">
<div class="detail-header">
<a href="#compare_levels/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">compare_levels(level, level)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L532" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>compare_levels(<a href="#t:level/0">level</a>(), <a href="#t:level/0">level</a>()) :: :lt | :eq | :gt</pre>
</div>
</div>
<section class="docstring">
<p>Compares log levels.</p>
<p>Receives two log levels and compares the <code class="inline">left</code> level
against the <code class="inline">right</code> level and returns:</p>
<ul>
<li><code class="inline">:lt</code> if <code class="inline">left</code> is less than <code class="inline">right</code>
</li>
<li><code class="inline">:eq</code> if <code class="inline">left</code> and <code class="inline">right</code> are equal
</li>
<li><code class="inline">:gt</code> if <code class="inline">left</code> is greater than <code class="inline">right</code>
</li>
</ul>
<h2 id="compare_levels/2-examples" class="section-heading">
<a href="#compare_levels/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="nc">Logger</span><span class="o">.</span><span class="n">compare_levels</span><span class="p" data-group-id="3469233280-1">(</span><span class="ss">:debug</span><span class="p">,</span><span class="w"> </span><span class="ss">:warn</span><span class="p" data-group-id="3469233280-1">)</span><span class="w">
</span><span class="ss">:lt</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Logger</span><span class="o">.</span><span class="n">compare_levels</span><span class="p" data-group-id="3469233280-2">(</span><span class="ss">:error</span><span class="p">,</span><span class="w"> </span><span class="ss">:info</span><span class="p" data-group-id="3469233280-2">)</span><span class="w">
</span><span class="ss">:gt</span></code></pre>
</section>
</div>
<div class="detail" id="configure/1">
<div class="detail-header">
<a href="#configure/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">configure(options)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L559" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>configure(<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Configures the logger.</p>
<p>See the “Runtime Configuration” section in the <a href="Logger.html#content"><code class="inline">Logger</code></a> module
documentation for the available options.</p>
</section>
</div>
<div class="detail" id="configure_backend/2">
<div class="detail-header">
<a href="#configure_backend/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">configure_backend(backend, options)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L641" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>configure_backend(<a href="#t:backend/0">backend</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Configures the given backend.</p>
<p>The backend needs to be started and running in order to
be configured at runtime.</p>
</section>
</div>
<div class="detail" id="debug/2">
<span id="debug/1"></span>
<div class="detail-header">
<a href="#debug/2" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">debug(chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L762" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Logs a debug message.</p>
<p>Returns <code class="inline">:ok</code> or an <code class="inline">{:error, reason}</code> tuple.</p>
<h2 id="debug/2-examples" class="section-heading">
<a href="#debug/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="nc">Logger</span><span class="o">.</span><span class="n">debug</span><span class="w"> </span><span class="s">"hello?"</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">debug</span><span class="w"> </span><span class="k" data-group-id="6678555527-1">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="s">"dynamically calculated debug"</span><span class="w"> </span><span class="k" data-group-id="6678555527-1">end</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">debug</span><span class="w"> </span><span class="k" data-group-id="6678555527-2">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p" data-group-id="6678555527-3">{</span><span class="s">"dynamically calculated debug"</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6678555527-4">[</span><span class="ss">additional</span><span class="p">:</span><span class="w"> </span><span class="ss">:metadata</span><span class="p" data-group-id="6678555527-4">]</span><span class="p" data-group-id="6678555527-3">}</span><span class="w"> </span><span class="k" data-group-id="6678555527-2">end</span></code></pre>
</section>
</div>
<div class="detail" id="disable/1">
<div class="detail-header">
<a href="#disable/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">disable(pid)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L493" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>disable(<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">pid</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Disables logging for the current process.</p>
<p>Currently the only accepted PID is <code class="inline">self()</code>.</p>
</section>
</div>
<div class="detail" id="enable/1">
<div class="detail-header">
<a href="#enable/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">enable(pid)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L482" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>enable(<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">pid</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Enables logging for the current process.</p>
<p>Currently the only accepted PID is <code class="inline">self()</code>.</p>
</section>
</div>
<div class="detail" id="error/2">
<span id="error/1"></span>
<div class="detail-header">
<a href="#error/2" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">error(chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L746" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Logs an error message.</p>
<p>Returns <code class="inline">:ok</code> or an <code class="inline">{:error, reason}</code> tuple.</p>
<h2 id="error/2-examples" class="section-heading">
<a href="#error/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="nc">Logger</span><span class="o">.</span><span class="n">error</span><span class="w"> </span><span class="s">"oops"</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">error</span><span class="w"> </span><span class="k" data-group-id="3002012553-1">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="s">"dynamically calculated error"</span><span class="w"> </span><span class="k" data-group-id="3002012553-1">end</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">error</span><span class="w"> </span><span class="k" data-group-id="3002012553-2">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p" data-group-id="3002012553-3">{</span><span class="s">"dynamically calculated error"</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="3002012553-4">[</span><span class="ss">additional</span><span class="p">:</span><span class="w"> </span><span class="ss">:metadata</span><span class="p" data-group-id="3002012553-4">]</span><span class="p" data-group-id="3002012553-3">}</span><span class="w"> </span><span class="k" data-group-id="3002012553-2">end</span></code></pre>
</section>
</div>
<div class="detail" id="flush/0">
<div class="detail-header">
<a href="#flush/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">flush()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L571" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>flush() :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Flushes the logger.</p>
<p>This guarantees all messages sent to <a href="Logger.html#content"><code class="inline">Logger</code></a> prior to this call will
be processed. This is useful for testing and it should not be called
in production code.</p>
</section>
</div>
<div class="detail" id="info/2">
<span id="info/1"></span>
<div class="detail-header">
<a href="#info/2" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">info(chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L730" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Logs an info message.</p>
<p>Returns <code class="inline">:ok</code> or an <code class="inline">{:error, reason}</code> tuple.</p>
<h2 id="info/2-examples" class="section-heading">
<a href="#info/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="nc">Logger</span><span class="o">.</span><span class="n">info</span><span class="w"> </span><span class="s">"mission accomplished"</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">info</span><span class="w"> </span><span class="k" data-group-id="3212322520-1">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="s">"dynamically calculated info"</span><span class="w"> </span><span class="k" data-group-id="3212322520-1">end</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">info</span><span class="w"> </span><span class="k" data-group-id="3212322520-2">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p" data-group-id="3212322520-3">{</span><span class="s">"dynamically calculated info"</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="3212322520-4">[</span><span class="ss">additional</span><span class="p">:</span><span class="w"> </span><span class="ss">:metadata</span><span class="p" data-group-id="3212322520-4">]</span><span class="p" data-group-id="3212322520-3">}</span><span class="w"> </span><span class="k" data-group-id="3212322520-2">end</span></code></pre>
</section>
</div>
<div class="detail" id="level/0">
<div class="detail-header">
<a href="#level/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">level()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L504" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>level() :: <a href="#t:level/0">level</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Retrieves the <a href="Logger.html#content"><code class="inline">Logger</code></a> level.</p>
<p>The <a href="Logger.html#content"><code class="inline">Logger</code></a> level can be changed via <a href="#configure/1"><code class="inline">configure/1</code></a>.</p>
</section>
</div>
<div class="detail" id="log/3">
<span id="log/2"></span>
<div class="detail-header">
<a href="#log/3" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">log(level, chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L776" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Logs a message with the given <code class="inline">level</code>.</p>
<p>Returns <code class="inline">:ok</code> or an <code class="inline">{:error, reason}</code> tuple.</p>
<p>The macros <a href="#debug/2"><code class="inline">debug/2</code></a>, <a href="#warn/2"><code class="inline">warn/2</code></a>, <a href="#info/2"><code class="inline">info/2</code></a>, and <a href="#error/2"><code class="inline">error/2</code></a> are
preferred over this macro as they can automatically eliminate
the call to <a href="Logger.html#content"><code class="inline">Logger</code></a> altogether at compile time if desired
(see the documentation for the <a href="Logger.html#content"><code class="inline">Logger</code></a> module).</p>
</section>
</div>
<div class="detail" id="metadata/0">
<div class="detail-header">
<a href="#metadata/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">metadata()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L462" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>metadata() :: <a href="#t:metadata/0">metadata</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Reads the current process metadata.</p>
</section>
</div>
<div class="detail" id="metadata/1">
<div class="detail-header">
<a href="#metadata/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">metadata(keyword)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L437" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>metadata(<a href="#t:metadata/0">metadata</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Alters the current process metadata according the given keyword list.</p>
<p>This function will merge the given keyword list into the existing metadata,
with the exception of setting a key to <code class="inline">nil</code>, which will remove that key
from the metadata.</p>
</section>
</div>
<div class="detail" id="remove_backend/2">
<span id="remove_backend/1"></span>
<div class="detail-header">
<a href="#remove_backend/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">remove_backend(backend, opts \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L612" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>remove_backend(<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()) :: :ok | {:error, <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Removes a backend.</p>
<h2 id="remove_backend/2-options" class="section-heading">
<a href="#remove_backend/2-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<ul>
<li><code class="inline">:flush</code> - when <code class="inline">true</code>, guarantees all messages currently sent
to <a href="Logger.html#content"><code class="inline">Logger</code></a> are processed before the backend is removed
</li>
</ul>
</section>
</div>
<div class="detail" id="remove_translator/1">
<div class="detail-header">
<a href="#remove_translator/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">remove_translator(translator)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L630" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>remove_translator({<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">module</a>(), function :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()}) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Removes a translator.</p>
</section>
</div>
<div class="detail" id="reset_metadata/1">
<span id="reset_metadata/0"></span>
<div class="detail-header">
<a href="#reset_metadata/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">reset_metadata(keywords \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L470" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>reset_metadata(<a href="#t:metadata/0">metadata</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Resets the current process metadata to the given keyword list.</p>
</section>
</div>
<div class="detail" id="warn/2">
<span id="warn/1"></span>
<div class="detail-header">
<a href="#warn/2" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">warn(chardata_or_fun, metadata \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger.ex#L714" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Logs a warning message.</p>
<p>Returns <code class="inline">:ok</code> or an <code class="inline">{:error, reason}</code> tuple.</p>
<h2 id="warn/2-examples" class="section-heading">
<a href="#warn/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="nc">Logger</span><span class="o">.</span><span class="n">warn</span><span class="w"> </span><span class="s">"knob turned too far to the right"</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">warn</span><span class="w"> </span><span class="k" data-group-id="1497644259-1">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="s">"dynamically calculated warning"</span><span class="w"> </span><span class="k" data-group-id="1497644259-1">end</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">warn</span><span class="w"> </span><span class="k" data-group-id="1497644259-2">fn</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p" data-group-id="1497644259-3">{</span><span class="s">"dynamically calculated warning"</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="1497644259-4">[</span><span class="ss">additional</span><span class="p">:</span><span class="w"> </span><span class="ss">:metadata</span><span class="p" data-group-id="1497644259-4">]</span><span class="p" data-group-id="1497644259-3">}</span><span class="w"> </span><span class="k" data-group-id="1497644259-2">end</span></code></pre>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
