/usr/share/doc/python-structlog-doc/html/loggers.html is in python-structlog-doc 17.2.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Loggers — structlog documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Configuration" href="configuration.html" />
<link rel="prev" title="Getting Started" href="getting-started.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="configuration.html" title="Configuration"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="getting-started.html" title="Getting Started"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">structlog documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="loggers">
<h1>Loggers<a class="headerlink" href="#loggers" title="Permalink to this headline">¶</a></h1>
<div class="section" id="bound-loggers">
<h2>Bound Loggers<a class="headerlink" href="#bound-loggers" title="Permalink to this headline">¶</a></h2>
<p>The center of <code class="docutils literal"><span class="pre">structlog</span></code> is the immutable log wrapper <code class="xref py py-class docutils literal"><span class="pre">BoundLogger</span></code>.</p>
<p>All it does is:</p>
<ul class="simple">
<li>Keep a <em>context dictionary</em> and a <em>logger</em> that it’s wrapping,</li>
<li>recreate itself with (optional) <em>additional</em> context data (the <code class="xref py py-func docutils literal"><span class="pre">bind()</span></code> and <code class="xref py py-func docutils literal"><span class="pre">new()</span></code> methods),</li>
<li>recreate itself with <em>less</em> data (<code class="xref py py-func docutils literal"><span class="pre">unbind()</span></code>),</li>
<li>and finally relay <em>all</em> other method calls to the wrapped logger<a class="footnote-reference" href="#id2" id="id1">[*]</a> after processing the log entry with the configured chain of <a class="reference internal" href="processors.html#processors"><span class="std std-ref">processors</span></a>.</li>
</ul>
<p>You won’t be instantiating it yourself though.
For that there is the <code class="xref py py-func docutils literal"><span class="pre">structlog.wrap_logger()</span></code> function (or the convenience function <code class="xref py py-func docutils literal"><span class="pre">structlog.get_logger()</span></code> we’ll discuss in a minute):</p>
<div class="highlight-default" id="proc"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">structlog</span> <span class="k">import</span> <span class="n">wrap_logger</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">PrintLogger</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">msg</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">proc</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">method_name</span><span class="p">,</span> <span class="n">event_dict</span><span class="p">):</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'I got called with'</span><span class="p">,</span> <span class="n">event_dict</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">return</span> <span class="nb">repr</span><span class="p">(</span><span class="n">event_dict</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">log</span> <span class="o">=</span> <span class="n">wrap_logger</span><span class="p">(</span><span class="n">PrintLogger</span><span class="p">(),</span> <span class="n">processors</span><span class="o">=</span><span class="p">[</span><span class="n">proc</span><span class="p">],</span> <span class="n">context_class</span><span class="o">=</span><span class="nb">dict</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">log2</span> <span class="o">=</span> <span class="n">log</span><span class="o">.</span><span class="n">bind</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">log</span> <span class="o">==</span> <span class="n">log2</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">log</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s1">'hello world'</span><span class="p">)</span>
<span class="go">I got called with {'event': 'hello world'}</span>
<span class="go">{'event': 'hello world'}</span>
<span class="gp">>>> </span><span class="n">log2</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s1">'hello world'</span><span class="p">)</span>
<span class="go">I got called with {'x': 42, 'event': 'hello world'}</span>
<span class="go">{'x': 42, 'event': 'hello world'}</span>
<span class="gp">>>> </span><span class="n">log3</span> <span class="o">=</span> <span class="n">log2</span><span class="o">.</span><span class="n">unbind</span><span class="p">(</span><span class="s1">'x'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">log</span> <span class="o">==</span> <span class="n">log3</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">log3</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s1">'nothing bound anymore'</span><span class="p">,</span> <span class="n">foo</span><span class="o">=</span><span class="s1">'but you can structure the event too'</span><span class="p">)</span>
<span class="go">I got called with {'foo': 'but you can structure the event too', 'event': 'nothing bound anymore'}</span>
<span class="go">{'foo': 'but you can structure the event too', 'event': 'nothing bound anymore'}</span>
</pre></div>
</div>
<p>As you can see, it accepts one mandatory and a few optional arguments:</p>
<dl class="docutils">
<dt><strong>logger</strong></dt>
<dd>The one and only positional argument is the logger that you want to wrap and to which the log entries will be proxied.
If you wish to use a <a class="reference internal" href="configuration.html#logger-factories"><span class="std std-ref">configured logger factory</span></a>, set it to <cite>None</cite>.</dd>
<dt><strong>processors</strong></dt>
<dd><p class="first">A list of callables that can <a class="reference internal" href="processors.html#processors"><span class="std std-ref">filter, mutate, and format</span></a> the log entry before it gets passed to the wrapped logger.</p>
<p class="last">Default is <code class="docutils literal"><span class="pre">[</span></code><code class="xref py py-func docutils literal"><span class="pre">format_exc_info()</span></code>, <code class="xref py py-class docutils literal"><span class="pre">KeyValueRenderer</span></code><code class="docutils literal"><span class="pre">]</span></code>.</p>
</dd>
<dt><strong>context_class</strong></dt>
<dd><p class="first">The class to save your context in.
Particularly useful for <a class="reference internal" href="thread-local.html#threadlocal"><span class="std std-ref">thread local context storage</span></a>.</p>
<p class="last">Default is <code class="xref py py-class docutils literal"><span class="pre">collections.OrderedDict</span></code>.</p>
</dd>
</dl>
<p>Additionally, the following arguments are allowed too:</p>
<dl class="docutils">
<dt><strong>wrapper_class</strong></dt>
<dd>A class to use instead of <code class="xref py py-class docutils literal"><span class="pre">BoundLogger</span></code> for wrapping.
This is useful if you want to sub-class BoundLogger and add custom logging methods.
BoundLogger’s bind/new methods are sub-classing friendly so you won’t have to re-implement them.
Please refer to the <a class="reference internal" href="custom-wrappers.html#wrapper-class-example"><span class="std std-ref">related example</span></a> for how this may look.</dd>
<dt><strong>initial_values</strong></dt>
<dd>The values that new wrapped loggers are automatically constructed with.
Useful for example if you want to have the module name as part of the context.</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Free your mind from the preconception that log entries have to be serialized to strings eventually.
All <code class="docutils literal"><span class="pre">structlog</span></code> cares about is a <em>dictionary</em> of <em>keys</em> and <em>values</em>.
What happens to it depends on the logger you wrap and your processors alone.</p>
<p class="last">This gives you the power to log directly to databases, log aggregation servers, web services, and whatnot.</p>
</div>
</div>
<div class="section" id="printing-and-testing">
<h2>Printing and Testing<a class="headerlink" href="#printing-and-testing" title="Permalink to this headline">¶</a></h2>
<p>To save you the hassle of using standard library logging for simple standard out logging, <code class="docutils literal"><span class="pre">structlog</span></code> ships a <code class="xref py py-class docutils literal"><span class="pre">PrintLogger</span></code> that can log into arbitrary files – including standard out (which is the default if no file is passed into the constructor):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">structlog</span> <span class="k">import</span> <span class="n">PrintLogger</span>
<span class="gp">>>> </span><span class="n">PrintLogger</span><span class="p">()</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'hello world!'</span><span class="p">)</span>
<span class="go">hello world!</span>
</pre></div>
</div>
<p>It’s handy for both examples and in combination with tools like <a class="reference external" href="http://smarden.org/runit/">runit</a> or <a class="reference external" href="https://hynek.me/articles/taking-some-pain-out-of-python-logging/">stdout/stderr-forwarding</a>.</p>
<p>Additionally – mostly for unit testing – <code class="docutils literal"><span class="pre">structlog</span></code> also ships with a logger that just returns whatever it gets passed into it: <code class="xref py py-class docutils literal"><span class="pre">ReturnLogger</span></code>.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">structlog</span> <span class="k">import</span> <span class="n">ReturnLogger</span>
<span class="gp">>>> </span><span class="n">ReturnLogger</span><span class="p">()</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">==</span> <span class="mi">42</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'hi'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">ReturnLogger</span><span class="p">()</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="ow">is</span> <span class="n">obj</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">ReturnLogger</span><span class="p">()</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">,</span> <span class="n">when</span><span class="o">=</span><span class="s1">'again'</span><span class="p">)</span>
<span class="go">(('hello',), {'when': 'again'})</span>
</pre></div>
</div>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[*]</a></td><td>Since this is slightly magicy, <code class="docutils literal"><span class="pre">structlog</span></code> comes with concrete loggers for the <a class="reference internal" href="standard-library.html"><span class="doc">Standard Library Logging</span></a> and <a class="reference internal" href="twisted.html"><span class="doc">Twisted</span></a> that offer you explicit APIs for the supported logging methods but behave identically like the generic BoundLogger otherwise.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Loggers</a><ul>
<li><a class="reference internal" href="#bound-loggers">Bound Loggers</a></li>
<li><a class="reference internal" href="#printing-and-testing">Printing and Testing</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="getting-started.html"
title="previous chapter">Getting Started</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="configuration.html"
title="next chapter">Configuration</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/loggers.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="configuration.html" title="Configuration"
>next</a> |</li>
<li class="right" >
<a href="getting-started.html" title="Getting Started"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">structlog documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, Hynek Schlawack.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>
|