/usr/share/doc/python-structlog-doc/html/twisted.html is in python-structlog-doc 15.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 | <!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>Twisted — structlog documentation</title>
<link rel="stylesheet" href="_static/default.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
};
</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="top" title="structlog documentation" href="index.html" />
<link rel="next" title="Logging Best Practices" href="logging-best-practices.html" />
<link rel="prev" title="Python Standard Library" href="standard-library.html" />
</head>
<body>
<div class="related">
<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="logging-best-practices.html" title="Logging Best Practices"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="standard-library.html" title="Python Standard Library"
accesskey="P">previous</a> |</li>
<li><a href="index.html">structlog documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="twisted">
<h1>Twisted<a class="headerlink" href="#twisted" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Since <tt class="xref py py-func docutils literal"><span class="pre">sys.exc_clear()</span></tt> has been dropped in Python 3, there is currently no way to avoid multiple tracebacks in your log files if using <tt class="docutils literal"><span class="pre">structlog</span></tt> together with Twisted on Python 3.</p>
</div>
<div class="section" id="concrete-bound-logger">
<h2>Concrete Bound Logger<a class="headerlink" href="#concrete-bound-logger" title="Permalink to this headline">¶</a></h2>
<p>To make structlog’s behavior less magicy, it ships with a Twisted-specific wrapper class that has an explicit API instead of improvising: <tt class="xref py py-class docutils literal"><span class="pre">structlog.twisted.BoundLogger</span></tt>.
It behaves exactly like the generic <tt class="xref py py-class docutils literal"><span class="pre">structlog.BoundLogger</span></tt> except:</p>
<ul class="simple">
<li>it’s slightly faster due to less overhead,</li>
<li>has an explicit API (<tt class="xref py py-func docutils literal"><span class="pre">msg()</span></tt> and <tt class="xref py py-func docutils literal"><span class="pre">err()</span></tt>),</li>
<li>hence causing less cryptic error messages if you get method names wrong.</li>
</ul>
<p>In order to avoid that structlog disturbs your CamelCase harmony, it comes with an alias for <tt class="xref py py-func docutils literal"><span class="pre">structlog.get_logger()</span></tt> called <tt class="xref py py-func docutils literal"><span class="pre">structlog.getLogger()</span></tt>.</p>
</div>
<div class="section" id="processors">
<h2>Processors<a class="headerlink" href="#processors" title="Permalink to this headline">¶</a></h2>
<p>structlog comes with two Twisted-specific processors:</p>
<dl class="docutils">
<dt><tt class="xref py py-class docutils literal"><span class="pre">EventAdapter</span></tt></dt>
<dd><p class="first">This is useful if you have an existing Twisted application and just want to wrap your loggers for now.
It takes care of transforming your event dictionary into something <a class="reference external" href="https://twistedmatrix.com/documents/current/api/twisted.python.log.html#err">twisted.python.log.err</a> can digest.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">onError</span><span class="p">(</span><span class="n">fail</span><span class="p">):</span>
<span class="n">failure</span> <span class="o">=</span> <span class="n">fail</span><span class="o">.</span><span class="n">trap</span><span class="p">(</span><span class="n">MoonExploded</span><span class="p">)</span>
<span class="n">log</span><span class="o">.</span><span class="n">err</span><span class="p">(</span><span class="n">failure</span><span class="p">,</span> <span class="n">_why</span><span class="o">=</span><span class="s">'event-that-happend'</span><span class="p">)</span>
</pre></div>
</div>
<p>will still work as expected.</p>
<p>Needs to be put at the end of the processing chain.
It formats the event using a renderer that needs to be passed into the constructor:</p>
<div class="highlight-python"><div class="highlight"><pre>configure(processors=[EventAdapter(KeyValueRenderer()])
</pre></div>
</div>
<p class="last">The drawback of this approach is that Twisted will format your exceptions as multi-line log entries which is painful to parse.
Therefore structlog comes with:</p>
</dd>
<dt><tt class="xref py py-class docutils literal"><span class="pre">JSONRenderer</span></tt></dt>
<dd>Goes a step further and circumvents Twisted logger’s Exception/Failure handling and renders it itself as JSON strings.
That gives you regular and simple-to-parse single-line JSON log entries no matter what happens.</dd>
</dl>
</div>
<div class="section" id="bending-foreign-logging-to-your-will">
<h2>Bending Foreign Logging To Your Will<a class="headerlink" href="#bending-foreign-logging-to-your-will" title="Permalink to this headline">¶</a></h2>
<p>structlog comes with a wrapper for Twisted’s log observers to ensure the rest of your logs are in JSON too: <tt class="xref py py-func docutils literal"><span class="pre">JSONLogObserverWrapper()</span></tt>.</p>
<p>What it does is determining whether a log entry has been formatted by <tt class="xref py py-class docutils literal"><span class="pre">JSONRenderer</span></tt> and if not, converts the log entry to JSON with <cite>event</cite> being the log message and putting Twisted’s <cite>system</cite> into a second key.</p>
<p>So for example:</p>
<div class="highlight-python"><div class="highlight"><pre>2013-09-15 22:02:18+0200 [-] Log opened.
</pre></div>
</div>
<p>becomes:</p>
<div class="highlight-python"><div class="highlight"><pre>2013-09-15 22:02:18+0200 [-] {"event": "Log opened.", "system": "-"}
</pre></div>
</div>
<p>There is obviously some redundancy here.
Also, I’m presuming that if you write out JSON logs, you’re going to let something else parse them which makes the human-readable date entries more trouble than they’re worth.</p>
<p>To get a clean log without timestamps and additional system fields (<tt class="docutils literal"><span class="pre">[-]</span></tt>), structlog comes with <tt class="xref py py-class docutils literal"><span class="pre">PlainFileLogObserver</span></tt> that writes only the plain message to a file and <tt class="xref py py-func docutils literal"><span class="pre">plainJSONStdOutLogger()</span></tt> that composes it with the aforementioned <tt class="xref py py-func docutils literal"><span class="pre">JSONLogObserverWrapper()</span></tt> and gives you a pure JSON log without any timestamps or other noise straight to <a class="reference external" href="http://en.wikipedia.org/wiki/Standard_out#Standard_output_.28stdout.29">standard out</a>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ twistd -n --logger structlog.twisted.plainJSONStdOutLogger web
{"event": "Log opened.", "system": "-"}
{"event": "twistd 13.1.0 (python 2.7.3) starting up.", "system": "-"}
{"event": "reactor class: twisted...EPollReactor.", "system": "-"}
{"event": "Site starting on 8080", "system": "-"}
{"event": "Starting factory <twisted.web.server.Site ...>", ...}
...
</pre></div>
</div>
</div>
<div class="section" id="suggested-configuration">
<h2>Suggested Configuration<a class="headerlink" href="#suggested-configuration" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">structlog</span>
<span class="n">structlog</span><span class="o">.</span><span class="n">configure</span><span class="p">(</span>
<span class="n">processors</span><span class="o">=</span><span class="p">[</span>
<span class="n">structlog</span><span class="o">.</span><span class="n">processors</span><span class="o">.</span><span class="n">StackInfoRenderer</span><span class="p">(),</span>
<span class="n">structlog</span><span class="o">.</span><span class="n">twisted</span><span class="o">.</span><span class="n">JSONRenderer</span><span class="p">()</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="n">logger_factory</span><span class="o">=</span><span class="n">structlog</span><span class="o">.</span><span class="n">twisted</span><span class="o">.</span><span class="n">LoggerFactory</span><span class="p">(),</span>
<span class="n">wrapper_class</span><span class="o">=</span><span class="n">structlog</span><span class="o">.</span><span class="n">twisted</span><span class="o">.</span><span class="n">BoundLogger</span><span class="p">,</span>
<span class="n">cache_logger_on_first_use</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>See also <a class="reference internal" href="logging-best-practices.html"><em>Logging Best Practices</em></a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Twisted</a><ul>
<li><a class="reference internal" href="#concrete-bound-logger">Concrete Bound Logger</a></li>
<li><a class="reference internal" href="#processors">Processors</a></li>
<li><a class="reference internal" href="#bending-foreign-logging-to-your-will">Bending Foreign Logging To Your Will</a></li>
<li><a class="reference internal" href="#suggested-configuration">Suggested Configuration</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="standard-library.html"
title="previous chapter">Python Standard Library</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="logging-best-practices.html"
title="next chapter">Logging Best Practices</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/twisted.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="logging-best-practices.html" title="Logging Best Practices"
>next</a> |</li>
<li class="right" >
<a href="standard-library.html" title="Python Standard Library"
>previous</a> |</li>
<li><a href="index.html">structlog documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2013-2015, Hynek Schlawack.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
|