<!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.Formatter – Logger v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/logger/v1.7/Logger.Formatter.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.Formatter
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L3" 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>Conveniences for formatting data for logs.</p>
<p>This module allows developers to specify a string that
serves as template for log messages, for example:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="n">time</span><span class="w"> </span><span class="err">$</span><span class="n">metadata</span><span class="p" data-group-id="1981602135-1">[</span><span class="err">$</span><span class="n">level</span><span class="p" data-group-id="1981602135-1">]</span><span class="w"> </span><span class="err">$</span><span class="n">message</span><span class="err">\</span><span class="n">n</span></code></pre>
<p>Will print error messages as:</p>
<pre><code class="nohighlight makeup elixir"><span class="mi">18</span><span class="p">:</span><span class="mi">43</span><span class="p">:</span><span class="mf">12.439</span><span class="w"> </span><span class="n">user_id</span><span class="o">=</span><span class="mi">13</span><span class="w"> </span><span class="p" data-group-id="9252357232-1">[</span><span class="n">error</span><span class="p" data-group-id="9252357232-1">]</span><span class="w"> </span><span class="nc">Hello</span><span class="err">\</span><span class="n">n</span></code></pre>
<p>The valid parameters you can use are:</p>
<ul>
<li><code class="inline">$time</code> - the time the log message was sent
</li>
<li><code class="inline">$date</code> - the date the log message was sent
</li>
<li><code class="inline">$message</code> - the log message
</li>
<li><code class="inline">$level</code> - the log level
</li>
<li><code class="inline">$node</code> - the node that prints the message
</li>
<li><code class="inline">$metadata</code> - user controlled data presented in <code class="inline">"key=val key2=val2 "</code> format
</li>
<li><code class="inline">$levelpad</code> - sets to a single space if level is 4 characters long,
otherwise set to the empty space. Used to align the message after level.
</li>
</ul>
<p>Backends typically allow developers to supply such control
strings via configuration files. This module provides <a href="#compile/1"><code class="inline">compile/1</code></a>,
which compiles the string into a format for fast operations at
runtime and <a href="#format/5"><code class="inline">format/5</code></a> to format the compiled pattern into an
actual IO data.</p>
<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>Metadata to be sent to the logger can be read and written with
the <a href="Logger.html#metadata/0"><code class="inline">Logger.metadata/0</code></a> and <a href="Logger.html#metadata/1"><code class="inline">Logger.metadata/1</code></a> functions. For example,
you can set <code class="inline">Logger.metadata([user_id: 13])</code> to add user_id metadata
to the current process. The user can configure the backend to choose
which metadata it wants to print and it will replace the <code class="inline">$metadata</code>
value.</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:pattern/0">pattern()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:time/0">time()</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="#compile/1">compile(pattern)</a>
</div>
<div class="summary-synopsis"><p>Compiles a format string into a data structure that <a href="#format/5"><code class="inline">format/5</code></a> can handle</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#format/5">format(config, level, msg, timestamp, metadata)</a>
</div>
<div class="summary-synopsis"><p>Takes a compiled format and injects the level, timestamp, message, and
metadata keyword list and returns a properly formatted string</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#format_date/1">format_date(arg)</a>
</div>
<div class="summary-synopsis"><p>Formats date as chardata</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#format_time/1">format_time(arg)</a>
</div>
<div class="summary-synopsis"><p>Formats time as chardata</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#prune/1">prune(binary)</a>
</div>
<div class="summary-synopsis"><p>Prunes non-valid UTF-8 codepoints</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:pattern/0">
<div class="detail-header">
<a href="#t:pattern/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">pattern()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L44" 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>pattern() :: :date | :level | :levelpad | :message | :metadata | :node | :time</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:time/0">
<div class="detail-header">
<a href="#t:time/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">time()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L43" 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>time() :: {{1970..10000, 1..12, 1..31}, {0..23, 0..59, 0..59, 0..999}}</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="compile/1">
<div class="detail-header">
<a href="#compile/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">compile(pattern)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L91" 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>compile(<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">binary</a>() | nil) :: [<a href="#t:pattern/0">pattern</a>() | <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">binary</a>()]</pre>
<pre>compile(pattern) :: pattern when pattern: {<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>()}</pre>
</div>
</div>
<section class="docstring">
<p>Compiles a format string into a data structure that <a href="#format/5"><code class="inline">format/5</code></a> can handle.</p>
<p>Check the module doc for documentation on the valid parameters that
will be interpolated in the pattern. If you pass <code class="inline">nil</code> as the pattern,
the pattern defaults to:</p>
<pre><code class="nohighlight makeup elixir"><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></code></pre>
<p>If you want to customize formatting through a custom formatter, you can
pass a <code class="inline">{module, function}</code> tuple as the <code class="inline">pattern</code>.</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="nc">Logger.Formatter</span><span class="o">.</span><span class="n">compile</span><span class="p" data-group-id="0134175263-1">(</span><span class="s">"$time $metadata [$level] $message</span><span class="se">\n</span><span class="s">"</span><span class="p" data-group-id="0134175263-1">)</span><span class="w">
</span><span class="p" data-group-id="0134175263-2">[</span><span class="ss">:time</span><span class="p">,</span><span class="w"> </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="s">" ["</span><span class="p">,</span><span class="w"> </span><span class="ss">:level</span><span class="p">,</span><span class="w"> </span><span class="s">"] "</span><span class="p">,</span><span class="w"> </span><span class="ss">:message</span><span class="p">,</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p" data-group-id="0134175263-2">]</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">Logger.Formatter</span><span class="o">.</span><span class="n">compile</span><span class="p" data-group-id="0134175263-3">(</span><span class="p" data-group-id="0134175263-4">{</span><span class="nc">MyLoggerFormatter</span><span class="p">,</span><span class="w"> </span><span class="ss">:format</span><span class="p" data-group-id="0134175263-4">}</span><span class="p" data-group-id="0134175263-3">)</span><span class="w">
</span><span class="p" data-group-id="0134175263-5">{</span><span class="nc">MyLoggerFormatter</span><span class="p">,</span><span class="w"> </span><span class="ss">:format</span><span class="p" data-group-id="0134175263-5">}</span></code></pre>
</section>
</div>
<div class="detail" id="format/5">
<div class="detail-header">
<a href="#format/5" 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">format(config, level, msg, timestamp, metadata)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L150" 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>format(
{<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>(), <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()} | [<a href="#t:pattern/0">pattern</a>() | <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">binary</a>()],
<a href="Logger.html#t:level/0">Logger.level</a>(),
<a href="Logger.html#t:message/0">Logger.message</a>(),
<a href="#t:time/0">time</a>(),
<a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()
) :: <a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Takes a compiled format and injects the level, timestamp, message, and
metadata keyword list and returns a properly formatted string.</p>
<h2 id="format/5-examples" class="section-heading">
<a href="#format/5-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="n">pattern</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Logger.Formatter</span><span class="o">.</span><span class="n">compile</span><span class="p" data-group-id="9385852679-1">(</span><span class="s">"[$level] $message"</span><span class="p" data-group-id="9385852679-1">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="n">timestamp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="9385852679-2">{</span><span class="p" data-group-id="9385852679-3">{</span><span class="mi">1977</span><span class="p">,</span><span class="w"> </span><span class="mi">01</span><span class="p">,</span><span class="w"> </span><span class="mi">28</span><span class="p" data-group-id="9385852679-3">}</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9385852679-4">{</span><span class="mi">13</span><span class="p">,</span><span class="w"> </span><span class="mi">29</span><span class="p">,</span><span class="w"> </span><span class="mi">00</span><span class="p">,</span><span class="w"> </span><span class="mi">000</span><span class="p" data-group-id="9385852679-4">}</span><span class="p" data-group-id="9385852679-2">}</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="n">formatted</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Logger.Formatter</span><span class="o">.</span><span class="n">format</span><span class="p" data-group-id="9385852679-5">(</span><span class="n">pattern</span><span class="p">,</span><span class="w"> </span><span class="ss">:info</span><span class="p">,</span><span class="w"> </span><span class="s">"hello"</span><span class="p">,</span><span class="w"> </span><span class="n">timestamp</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9385852679-6">[</span><span class="p" data-group-id="9385852679-6">]</span><span class="p" data-group-id="9385852679-5">)</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">IO</span><span class="o">.</span><span class="n">chardata_to_string</span><span class="p" data-group-id="9385852679-7">(</span><span class="n">formatted</span><span class="p" data-group-id="9385852679-7">)</span><span class="w">
</span><span class="s">"[info] hello"</span></code></pre>
</section>
</div>
<div class="detail" id="format_date/1">
<div class="detail-header">
<a href="#format_date/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">format_date(arg)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L120" 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>format_date({1970..10000, 1..12, 1..31}) :: <a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Formats date as chardata.</p>
</section>
</div>
<div class="detail" id="format_time/1">
<div class="detail-header">
<a href="#format_time/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">format_time(arg)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L112" 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>format_time({0..23, 0..59, 0..59, 0..999}) :: <a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Formats time as chardata.</p>
</section>
</div>
<div class="detail" id="prune/1">
<div class="detail-header">
<a href="#prune/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">prune(binary)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/logger/lib/logger/formatter.ex#L59" 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>prune(<a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>()) :: <a href="https://hexdocs.pm/elixir/IO.html#t:chardata/0">IO.chardata</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Prunes non-valid UTF-8 codepoints.</p>
<p>Typically called after formatting when the data cannot be printed.</p>
</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>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
016232f1d9a3f7bee85855d35a2bca58
>
files
>
175
