/usr/share/doc/python-structlog-doc/html/why.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 | <!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>Why… — 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="Getting Started" href="getting-started.html" />
<link rel="prev" title="Structured Logging for Python" href="index.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="getting-started.html" title="Getting Started"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Structured Logging for Python"
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="why">
<h1>Why…<a class="headerlink" href="#why" title="Permalink to this headline">¶</a></h1>
<div class="section" id="structured-logging">
<h2>…Structured Logging?<a class="headerlink" href="#structured-logging" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div><p>I believe the widespread use of format strings in logging is based on two presumptions:</p>
<ul class="simple">
<li>The first level consumer of a log message is a human.</li>
<li>The programmer knows what information is needed to debug an issue.</li>
</ul>
<p>I believe these presumptions are <strong>no longer correct</strong> in server side software.</p>
<p class="attribution">—<a class="reference external" href="https://journal.paul.querna.org/articles/2011/12/26/log-for-machines-in-json/">Paul Querna</a></p>
</div></blockquote>
<p>Structured logging means that you don’t write hard-to-parse and hard-to-keep-consistent prose in your logs but that you log <em>events</em> that happen in a <em>context</em> instead.</p>
</div>
<div class="section" id="structlog">
<h2>…structlog?<a class="headerlink" href="#structlog" title="Permalink to this headline">¶</a></h2>
<p>Because it’s easy and you don’t have to replace your underlying logger (but you can!) – you just add structure to your log entries and format them to strings before they hit your real loggers.</p>
<p><code class="docutils literal"><span class="pre">structlog</span></code> supports you with accepting key/value pairs as arguments, building your context as you go (e.g. if a user logs in, you bind their user name to your current logger) and log events when they happen (i.e. the user does something log-worthy):</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">get_logger</span>
<span class="gp">>>> </span><span class="n">log</span> <span class="o">=</span> <span class="n">get_logger</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">log</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">user</span><span class="o">=</span><span class="s1">'anonymous'</span><span class="p">,</span> <span class="n">some_key</span><span class="o">=</span><span class="mi">23</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">log</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">user</span><span class="o">=</span><span class="s1">'hynek'</span><span class="p">,</span> <span class="n">another_key</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">info</span><span class="p">(</span><span class="s1">'user.logged_in'</span><span class="p">,</span> <span class="n">happy</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">2016-04-20 16:20.13 user.logged_in another_key=42 happy=True some_key=23 user='hynek'</span>
</pre></div>
</div>
<p>This ability to bind key/values pairs to a logger frees you from using conditionals, closures, or boilerplate methods to log out all relevant data.</p>
<p>Additionally, <code class="docutils literal"><span class="pre">structlog</span></code> offers you a flexible way to <em>filter</em> and <em>modify</em> your log entries using so called <a class="reference internal" href="processors.html#processors"><span class="std std-ref">processors</span></a> before the entry is passed to your real logger.
The possibilities include <code class="xref py py-class docutils literal"><span class="pre">logging</span> <span class="pre">in</span> <span class="pre">JSON</span></code>, adding arbitrary meta data like <code class="xref py py-class docutils literal"><span class="pre">timestamps</span></code>, counting events as metrics, or <a class="reference internal" href="processors.html#cond-drop"><span class="std std-ref">dropping log entries</span></a> caused by your monitoring system.</p>
<p><code class="docutils literal"><span class="pre">structlog</span></code> is also flexible enough to allow transparent <a class="reference internal" href="thread-local.html#threadlocal"><span class="std std-ref">thread local</span></a> storage for your context if you don’t like the idea of local bindings as in the example above.</p>
</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="#">Why…</a><ul>
<li><a class="reference internal" href="#structured-logging">…Structured Logging?</a></li>
<li><a class="reference internal" href="#structlog">…structlog?</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Structured Logging for Python</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="getting-started.html"
title="next chapter">Getting Started</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/why.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="getting-started.html" title="Getting Started"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Structured Logging for Python"
>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>
|