This file is indexed.

/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 &mdash; 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> &raquo;</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&#8217;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&#8217;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">&#39;event-that-happend&#39;</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&#8217;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&#8217;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&#8217;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 [-] {&quot;event&quot;: &quot;Log opened.&quot;, &quot;system&quot;: &quot;-&quot;}
</pre></div>
</div>
<p>There is obviously some redundancy here.
Also, I&#8217;m presuming that if you write out JSON logs, you&#8217;re going to let something else parse them which makes the human-readable date entries more trouble than they&#8217;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
{&quot;event&quot;: &quot;Log opened.&quot;, &quot;system&quot;: &quot;-&quot;}
{&quot;event&quot;: &quot;twistd 13.1.0 (python 2.7.3) starting up.&quot;, &quot;system&quot;: &quot;-&quot;}
{&quot;event&quot;: &quot;reactor class: twisted...EPollReactor.&quot;, &quot;system&quot;: &quot;-&quot;}
{&quot;event&quot;: &quot;Site starting on 8080&quot;, &quot;system&quot;: &quot;-&quot;}
{&quot;event&quot;: &quot;Starting factory &lt;twisted.web.server.Site ...&gt;&quot;, ...}
...
</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> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2013-2015, Hynek Schlawack.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
    </div>
  </body>
</html>