Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Watch 1
Star 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branch: master
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/howto/logging-cookbook.html

4321 lines
499KB
Raw Permalink Blame History 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="Logging Cookbook" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/howto/logging-cookbook.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Author, Vinay Sajip <vinay_sajip at red-dove dot com>,. This page contains a number of recipes related to logging, which have been found useful in the past. For links to tutorial and reference info..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Author, Vinay Sajip <vinay_sajip at red-dove dot com>,. This page contains a number of recipes related to logging, which have been found useful in the past. For links to tutorial and reference info..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>Logging Cookbook &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="Regular Expression HOWTO" href="regex.html" />

  39.     <link rel="prev" title="Logging HOWTO" href="logging.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/howto/logging-cookbook.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#">Logging Cookbook</a><ul>

  99. <li><a class="reference internal" href="#using-logging-in-multiple-modules">Using logging in multiple modules</a></li>

  100. <li><a class="reference internal" href="#logging-from-multiple-threads">Logging from multiple threads</a></li>

  101. <li><a class="reference internal" href="#multiple-handlers-and-formatters">Multiple handlers and formatters</a></li>

  102. <li><a class="reference internal" href="#logging-to-multiple-destinations">Logging to multiple destinations</a></li>

  103. <li><a class="reference internal" href="#custom-handling-of-levels">Custom handling of levels</a></li>

  104. <li><a class="reference internal" href="#configuration-server-example">Configuration server example</a></li>

  105. <li><a class="reference internal" href="#dealing-with-handlers-that-block">Dealing with handlers that block</a></li>

  106. <li><a class="reference internal" href="#sending-and-receiving-logging-events-across-a-network">Sending and receiving logging events across a network</a><ul>

  107. <li><a class="reference internal" href="#running-a-logging-socket-listener-in-production">Running a logging socket listener in production</a></li>

  108. </ul>

  109. </li>

  110. <li><a class="reference internal" href="#adding-contextual-information-to-your-logging-output">Adding contextual information to your logging output</a><ul>

  111. <li><a class="reference internal" href="#using-loggeradapters-to-impart-contextual-information">Using LoggerAdapters to impart contextual information</a><ul>

  112. <li><a class="reference internal" href="#using-objects-other-than-dicts-to-pass-contextual-information">Using objects other than dicts to pass contextual information</a></li>

  113. </ul>

  114. </li>

  115. <li><a class="reference internal" href="#using-filters-to-impart-contextual-information">Using Filters to impart contextual information</a></li>

  116. </ul>

  117. </li>

  118. <li><a class="reference internal" href="#use-of-contextvars">Use of <code class="docutils literal notranslate"><span class="pre">contextvars</span></code></a></li>

  119. <li><a class="reference internal" href="#imparting-contextual-information-in-handlers">Imparting contextual information in handlers</a></li>

  120. <li><a class="reference internal" href="#logging-to-a-single-file-from-multiple-processes">Logging to a single file from multiple processes</a><ul>

  121. <li><a class="reference internal" href="#using-concurrent-futures-processpoolexecutor">Using concurrent.futures.ProcessPoolExecutor</a></li>

  122. <li><a class="reference internal" href="#deploying-web-applications-using-gunicorn-and-uwsgi">Deploying Web applications using Gunicorn and uWSGI</a></li>

  123. </ul>

  124. </li>

  125. <li><a class="reference internal" href="#using-file-rotation">Using file rotation</a></li>

  126. <li><a class="reference internal" href="#use-of-alternative-formatting-styles">Use of alternative formatting styles</a></li>

  127. <li><a class="reference internal" href="#customizing-logrecord">Customizing <code class="docutils literal notranslate"><span class="pre">LogRecord</span></code></a></li>

  128. <li><a class="reference internal" href="#subclassing-queuehandler-and-queuelistener-a-zeromq-example">Subclassing QueueHandler and QueueListener- a ZeroMQ example</a><ul>

  129. <li><a class="reference internal" href="#subclass-queuehandler">Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code></a></li>

  130. <li><a class="reference internal" href="#subclass-queuelistener">Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code></a></li>

  131. </ul>

  132. </li>

  133. <li><a class="reference internal" href="#subclassing-queuehandler-and-queuelistener-a-pynng-example">Subclassing QueueHandler and QueueListener- a <code class="docutils literal notranslate"><span class="pre">pynng</span></code> example</a><ul>

  134. <li><a class="reference internal" href="#id3">Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code></a></li>

  135. <li><a class="reference internal" href="#id4">Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code></a></li>

  136. </ul>

  137. </li>

  138. <li><a class="reference internal" href="#an-example-dictionary-based-configuration">An example dictionary-based configuration</a></li>

  139. <li><a class="reference internal" href="#using-a-rotator-and-namer-to-customize-log-rotation-processing">Using a rotator and namer to customize log rotation processing</a></li>

  140. <li><a class="reference internal" href="#a-more-elaborate-multiprocessing-example">A more elaborate multiprocessing example</a></li>

  141. <li><a class="reference internal" href="#inserting-a-bom-into-messages-sent-to-a-sysloghandler">Inserting a BOM into messages sent to a SysLogHandler</a></li>

  142. <li><a class="reference internal" href="#implementing-structured-logging">Implementing structured logging</a></li>

  143. <li><a class="reference internal" href="#customizing-handlers-with-dictconfig">Customizing handlers with <code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a></li>

  144. <li><a class="reference internal" href="#using-particular-formatting-styles-throughout-your-application">Using particular formatting styles throughout your application</a><ul>

  145. <li><a class="reference internal" href="#using-logrecord-factories">Using LogRecord factories</a></li>

  146. <li><a class="reference internal" href="#using-custom-message-objects">Using custom message objects</a></li>

  147. </ul>

  148. </li>

  149. <li><a class="reference internal" href="#configuring-filters-with-dictconfig">Configuring filters with <code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a></li>

  150. <li><a class="reference internal" href="#customized-exception-formatting">Customized exception formatting</a></li>

  151. <li><a class="reference internal" href="#speaking-logging-messages">Speaking logging messages</a></li>

  152. <li><a class="reference internal" href="#buffering-logging-messages-and-outputting-them-conditionally">Buffering logging messages and outputting them conditionally</a></li>

  153. <li><a class="reference internal" href="#sending-logging-messages-to-email-with-buffering">Sending logging messages to email, with buffering</a></li>

  154. <li><a class="reference internal" href="#formatting-times-using-utc-gmt-via-configuration">Formatting times using UTC (GMT) via configuration</a></li>

  155. <li><a class="reference internal" href="#using-a-context-manager-for-selective-logging">Using a context manager for selective logging</a></li>

  156. <li><a class="reference internal" href="#a-cli-application-starter-template">A CLI application starter template</a></li>

  157. <li><a class="reference internal" href="#a-qt-gui-for-logging">A Qt GUI for logging</a></li>

  158. <li><a class="reference internal" href="#logging-to-syslog-with-rfc5424-support">Logging to syslog with RFC5424 support</a></li>

  159. <li><a class="reference internal" href="#how-to-treat-a-logger-like-an-output-stream">How to treat a logger like an output stream</a></li>

  160. <li><a class="reference internal" href="#patterns-to-avoid">Patterns to avoid</a><ul>

  161. <li><a class="reference internal" href="#opening-the-same-log-file-multiple-times">Opening the same log file multiple times</a></li>

  162. <li><a class="reference internal" href="#using-loggers-as-attributes-in-a-class-or-passing-them-as-parameters">Using loggers as attributes in a class or passing them as parameters</a></li>

  163. <li><a class="reference internal" href="#adding-handlers-other-than-nullhandler-to-a-logger-in-a-library">Adding handlers other than <code class="xref py py-class docutils literal notranslate"><span class="pre">NullHandler</span></code> to a logger in a library</a></li>

  164. <li><a class="reference internal" href="#creating-a-lot-of-loggers">Creating a lot of loggers</a></li>

  165. </ul>

  166. </li>

  167. <li><a class="reference internal" href="#other-resources">Other resources</a></li>

  168. </ul>

  169. </li>

  170. </ul>

  171. 

  172.   </div>

  173.   <div>

  174.     <h4>Previous topic</h4>

  175.     <p class="topless"><a href="logging.html"

  176.                           title="previous chapter">Logging HOWTO</a></p>

  177.   </div>

  178.   <div>

  179.     <h4>Next topic</h4>

  180.     <p class="topless"><a href="regex.html"

  181.                           title="next chapter">Regular Expression HOWTO</a></p>

  182.   </div>

  183.   <div role="note" aria-label="source link">

  184.     <h3>This Page</h3>

  185.     <ul class="this-page-menu">

  186.       <li><a href="../bugs.html">Report a Bug</a></li>

  187.       <li>

  188.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/logging-cookbook.rst"

  189.             rel="nofollow">Show Source

  190.         </a>

  191.       </li>

  192.     </ul>

  193.   </div>

  194.         </nav>

  195.     </div>

  196. </div>

  197. 

  198.   

  199.     <div class="related" role="navigation" aria-label="related navigation">

  200.       <h3>Navigation</h3>

  201.       <ul>

  202.         <li class="right" style="margin-right: 10px">

  203.           <a href="../genindex.html" title="General Index"

  204.              accesskey="I">index</a></li>

  205.         <li class="right" >

  206.           <a href="../py-modindex.html" title="Python Module Index"

  207.              >modules</a> |</li>

  208.         <li class="right" >

  209.           <a href="regex.html" title="Regular Expression HOWTO"

  210.              accesskey="N">next</a> |</li>

  211.         <li class="right" >

  212.           <a href="logging.html" title="Logging HOWTO"

  213.              accesskey="P">previous</a> |</li>

  214. 

  215.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  216.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  217.           <li class="switchers">

  218.             <div class="language_switcher_placeholder"></div>

  219.             <div class="version_switcher_placeholder"></div>

  220.           </li>

  221.           <li>

  222.               

  223.           </li>

  224.     <li id="cpython-language-and-version">

  225.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  226.     </li>

  227. 

  228.           <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> &#187;</li>

  229.         <li class="nav-item nav-item-this"><a href="">Logging Cookbook</a></li>

  230.                 <li class="right">

  231.                     

  232. 

  233.     <div class="inline-search" role="search">

  234.         <form class="inline-search" action="../search.html" method="get">

  235.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  236.           <input type="submit" value="Go" />

  237.         </form>

  238.     </div>

  239.                      |

  240.                 </li>

  241.             <li class="right">

  242. <label class="theme-selector-label">

  243.     Theme

  244.     <select class="theme-selector" oninput="activateTheme(this.value)">

  245.         <option value="auto" selected>Auto</option>

  246.         <option value="light">Light</option>

  247.         <option value="dark">Dark</option>

  248.     </select>

  249. </label> |</li>

  250.             

  251.       </ul>

  252.     </div>    

  253. 

  254.     <div class="document">

  255.       <div class="documentwrapper">

  256.         <div class="bodywrapper">

  257.           <div class="body" role="main">

  258.             

  259.   <section id="logging-cookbook">

  260. <span id="id1"></span><h1>Logging Cookbook<a class="headerlink" href="#logging-cookbook" title="Link to this heading">¶</a></h1>

  261. <dl class="field-list simple">

  262. <dt class="field-odd">Author<span class="colon">:</span></dt>

  263. <dd class="field-odd"><p>Vinay Sajip &lt;vinay_sajip at red-dove dot com&gt;</p>

  264. </dd>

  265. </dl>

  266. <p>This page contains a number of recipes related to logging, which have been found

  267. useful in the past. For links to tutorial and reference information, please see

  268. <a class="reference internal" href="#cookbook-ref-links"><span class="std std-ref">Other resources</span></a>.</p>

  269. <section id="using-logging-in-multiple-modules">

  270. <h2>Using logging in multiple modules<a class="headerlink" href="#using-logging-in-multiple-modules" title="Link to this heading">¶</a></h2>

  271. <p>Multiple calls to <code class="docutils literal notranslate"><span class="pre">logging.getLogger('someLogger')</span></code> return a reference to the

  272. same logger object.  This is true not only within the same module, but also

  273. across modules as long as it is in the same Python interpreter process.  It is

  274. true for references to the same object; additionally, application code can

  275. define and configure a parent logger in one module and create (but not

  276. configure) a child logger in a separate module, and all logger calls to the

  277. child will pass up to the parent.  Here is a main module:</p>

  278. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  279. <span class="kn">import</span> <span class="nn">auxiliary_module</span>

  280. 

  281. <span class="c1"># create logger with &#39;spam_application&#39;</span>

  282. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;spam_application&#39;</span><span class="p">)</span>

  283. <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  284. <span class="c1"># create file handler which logs even debug messages</span>

  285. <span class="n">fh</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="s1">&#39;spam.log&#39;</span><span class="p">)</span>

  286. <span class="n">fh</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  287. <span class="c1"># create console handler with a higher log level</span>

  288. <span class="n">ch</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  289. <span class="n">ch</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">)</span>

  290. <span class="c1"># create formatter and add it to the handlers</span>

  291. <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> - </span><span class="si">%(name)s</span><span class="s1"> - </span><span class="si">%(levelname)s</span><span class="s1"> - </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  292. <span class="n">fh</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  293. <span class="n">ch</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  294. <span class="c1"># add the handlers to the logger</span>

  295. <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">fh</span><span class="p">)</span>

  296. <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">ch</span><span class="p">)</span>

  297. 

  298. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;creating an instance of auxiliary_module.Auxiliary&#39;</span><span class="p">)</span>

  299. <span class="n">a</span> <span class="o">=</span> <span class="n">auxiliary_module</span><span class="o">.</span><span class="n">Auxiliary</span><span class="p">()</span>

  300. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;created an instance of auxiliary_module.Auxiliary&#39;</span><span class="p">)</span>

  301. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;calling auxiliary_module.Auxiliary.do_something&#39;</span><span class="p">)</span>

  302. <span class="n">a</span><span class="o">.</span><span class="n">do_something</span><span class="p">()</span>

  303. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;finished auxiliary_module.Auxiliary.do_something&#39;</span><span class="p">)</span>

  304. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;calling auxiliary_module.some_function()&#39;</span><span class="p">)</span>

  305. <span class="n">auxiliary_module</span><span class="o">.</span><span class="n">some_function</span><span class="p">()</span>

  306. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;done with auxiliary_module.some_function()&#39;</span><span class="p">)</span>

  307. </pre></div>

  308. </div>

  309. <p>Here is the auxiliary module:</p>

  310. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  311. 

  312. <span class="c1"># create logger</span>

  313. <span class="n">module_logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;spam_application.auxiliary&#39;</span><span class="p">)</span>

  314. 

  315. <span class="k">class</span> <span class="nc">Auxiliary</span><span class="p">:</span>

  316.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  317.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;spam_application.auxiliary.Auxiliary&#39;</span><span class="p">)</span>

  318.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;creating an instance of Auxiliary&#39;</span><span class="p">)</span>

  319. 

  320.     <span class="k">def</span> <span class="nf">do_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  321.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;doing something&#39;</span><span class="p">)</span>

  322.         <span class="n">a</span> <span class="o">=</span> <span class="mi">1</span> <span class="o">+</span> <span class="mi">1</span>

  323.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;done doing something&#39;</span><span class="p">)</span>

  324. 

  325. <span class="k">def</span> <span class="nf">some_function</span><span class="p">():</span>

  326.     <span class="n">module_logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;received a call to &quot;some_function&quot;&#39;</span><span class="p">)</span>

  327. </pre></div>

  328. </div>

  329. <p>The output looks like this:</p>

  330. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2005-03-23 23:47:11,663 - spam_application - INFO -

  331.    creating an instance of auxiliary_module.Auxiliary

  332. 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -

  333.    creating an instance of Auxiliary

  334. 2005-03-23 23:47:11,665 - spam_application - INFO -

  335.    created an instance of auxiliary_module.Auxiliary

  336. 2005-03-23 23:47:11,668 - spam_application - INFO -

  337.    calling auxiliary_module.Auxiliary.do_something

  338. 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -

  339.    doing something

  340. 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -

  341.    done doing something

  342. 2005-03-23 23:47:11,670 - spam_application - INFO -

  343.    finished auxiliary_module.Auxiliary.do_something

  344. 2005-03-23 23:47:11,671 - spam_application - INFO -

  345.    calling auxiliary_module.some_function()

  346. 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -

  347.    received a call to &#39;some_function&#39;

  348. 2005-03-23 23:47:11,673 - spam_application - INFO -

  349.    done with auxiliary_module.some_function()

  350. </pre></div>

  351. </div>

  352. </section>

  353. <section id="logging-from-multiple-threads">

  354. <h2>Logging from multiple threads<a class="headerlink" href="#logging-from-multiple-threads" title="Link to this heading">¶</a></h2>

  355. <p>Logging from multiple threads requires no special effort. The following example

  356. shows logging from the main (initial) thread and another thread:</p>

  357. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  358. <span class="kn">import</span> <span class="nn">threading</span>

  359. <span class="kn">import</span> <span class="nn">time</span>

  360. 

  361. <span class="k">def</span> <span class="nf">worker</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>

  362.     <span class="k">while</span> <span class="ow">not</span> <span class="n">arg</span><span class="p">[</span><span class="s1">&#39;stop&#39;</span><span class="p">]:</span>

  363.         <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Hi from myfunc&#39;</span><span class="p">)</span>

  364.         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.5</span><span class="p">)</span>

  365. 

  366. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  367.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(relativeCreated)6d</span><span class="s1"> </span><span class="si">%(threadName)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  368.     <span class="n">info</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;stop&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">}</span>

  369.     <span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">worker</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">info</span><span class="p">,))</span>

  370.     <span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  371.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  372.         <span class="k">try</span><span class="p">:</span>

  373.             <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Hello from main&#39;</span><span class="p">)</span>

  374.             <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.75</span><span class="p">)</span>

  375.         <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>

  376.             <span class="n">info</span><span class="p">[</span><span class="s1">&#39;stop&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>

  377.             <span class="k">break</span>

  378.     <span class="n">thread</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  379. 

  380. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  381.     <span class="n">main</span><span class="p">()</span>

  382. </pre></div>

  383. </div>

  384. <p>When run, the script should print something like the following:</p>

  385. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>   0 Thread-1 Hi from myfunc

  386.    3 MainThread Hello from main

  387.  505 Thread-1 Hi from myfunc

  388.  755 MainThread Hello from main

  389. 1007 Thread-1 Hi from myfunc

  390. 1507 MainThread Hello from main

  391. 1508 Thread-1 Hi from myfunc

  392. 2010 Thread-1 Hi from myfunc

  393. 2258 MainThread Hello from main

  394. 2512 Thread-1 Hi from myfunc

  395. 3009 MainThread Hello from main

  396. 3013 Thread-1 Hi from myfunc

  397. 3515 Thread-1 Hi from myfunc

  398. 3761 MainThread Hello from main

  399. 4017 Thread-1 Hi from myfunc

  400. 4513 MainThread Hello from main

  401. 4518 Thread-1 Hi from myfunc

  402. </pre></div>

  403. </div>

  404. <p>This shows the logging output interspersed as one might expect. This approach

  405. works for more threads than shown here, of course.</p>

  406. </section>

  407. <section id="multiple-handlers-and-formatters">

  408. <h2>Multiple handlers and formatters<a class="headerlink" href="#multiple-handlers-and-formatters" title="Link to this heading">¶</a></h2>

  409. <p>Loggers are plain Python objects.  The <a class="reference internal" href="../library/logging.html#logging.Logger.addHandler" title="logging.Logger.addHandler"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addHandler()</span></code></a> method has no

  410. minimum or maximum quota for the number of handlers you may add.  Sometimes it

  411. will be beneficial for an application to log all messages of all severities to a

  412. text file while simultaneously logging errors or above to the console.  To set

  413. this up, simply configure the appropriate handlers.  The logging calls in the

  414. application code will remain unchanged.  Here is a slight modification to the

  415. previous simple module-based configuration example:</p>

  416. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  417. 

  418. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;simple_example&#39;</span><span class="p">)</span>

  419. <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  420. <span class="c1"># create file handler which logs even debug messages</span>

  421. <span class="n">fh</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="s1">&#39;spam.log&#39;</span><span class="p">)</span>

  422. <span class="n">fh</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  423. <span class="c1"># create console handler with a higher log level</span>

  424. <span class="n">ch</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  425. <span class="n">ch</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">)</span>

  426. <span class="c1"># create formatter and add it to the handlers</span>

  427. <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> - </span><span class="si">%(name)s</span><span class="s1"> - </span><span class="si">%(levelname)s</span><span class="s1"> - </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  428. <span class="n">ch</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  429. <span class="n">fh</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  430. <span class="c1"># add the handlers to logger</span>

  431. <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">ch</span><span class="p">)</span>

  432. <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">fh</span><span class="p">)</span>

  433. 

  434. <span class="c1"># &#39;application&#39; code</span>

  435. <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;debug message&#39;</span><span class="p">)</span>

  436. <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;info message&#39;</span><span class="p">)</span>

  437. <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;warn message&#39;</span><span class="p">)</span>

  438. <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;error message&#39;</span><span class="p">)</span>

  439. <span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;critical message&#39;</span><span class="p">)</span>

  440. </pre></div>

  441. </div>

  442. <p>Notice that the ‘application’ code does not care about multiple handlers.  All

  443. that changed was the addition and configuration of a new handler named <em>fh</em>.</p>

  444. <p>The ability to create new handlers with higher- or lower-severity filters can be

  445. very helpful when writing and testing an application.  Instead of using many

  446. <code class="docutils literal notranslate"><span class="pre">print</span></code> statements for debugging, use <code class="docutils literal notranslate"><span class="pre">logger.debug</span></code>: Unlike the print

  447. statements, which you will have to delete or comment out later, the logger.debug

  448. statements can remain intact in the source code and remain dormant until you

  449. need them again.  At that time, the only change that needs to happen is to

  450. modify the severity level of the logger and/or handler to debug.</p>

  451. </section>

  452. <section id="logging-to-multiple-destinations">

  453. <span id="multiple-destinations"></span><h2>Logging to multiple destinations<a class="headerlink" href="#logging-to-multiple-destinations" title="Link to this heading">¶</a></h2>

  454. <p>Let’s say you want to log to console and file with different message formats and

  455. in differing circumstances. Say you want to log messages with levels of DEBUG

  456. and higher to file, and those messages at level INFO and higher to the console.

  457. Let’s also assume that the file should contain timestamps, but the console

  458. messages should not. Here’s how you can achieve this:</p>

  459. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  460. 

  461. <span class="c1"># set up logging to file - see previous section for more details</span>

  462. <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span>

  463.                     <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(name)-12s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">,</span>

  464.                     <span class="n">datefmt</span><span class="o">=</span><span class="s1">&#39;%m-</span><span class="si">%d</span><span class="s1"> %H:%M&#39;</span><span class="p">,</span>

  465.                     <span class="n">filename</span><span class="o">=</span><span class="s1">&#39;/tmp/myapp.log&#39;</span><span class="p">,</span>

  466.                     <span class="n">filemode</span><span class="o">=</span><span class="s1">&#39;w&#39;</span><span class="p">)</span>

  467. <span class="c1"># define a Handler which writes INFO messages or higher to the sys.stderr</span>

  468. <span class="n">console</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  469. <span class="n">console</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  470. <span class="c1"># set a format which is simpler for console use</span>

  471. <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(name)-12s</span><span class="s1">: </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  472. <span class="c1"># tell the handler to use this format</span>

  473. <span class="n">console</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  474. <span class="c1"># add the handler to the root logger</span>

  475. <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">console</span><span class="p">)</span>

  476. 

  477. <span class="c1"># Now, we can log to the root logger, or any other logger. First the root...</span>

  478. <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Jackdaws love my big sphinx of quartz.&#39;</span><span class="p">)</span>

  479. 

  480. <span class="c1"># Now, define a couple of other loggers which might represent areas in your</span>

  481. <span class="c1"># application:</span>

  482. 

  483. <span class="n">logger1</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;myapp.area1&#39;</span><span class="p">)</span>

  484. <span class="n">logger2</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;myapp.area2&#39;</span><span class="p">)</span>

  485. 

  486. <span class="n">logger1</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Quick zephyrs blow, vexing daft Jim.&#39;</span><span class="p">)</span>

  487. <span class="n">logger1</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;How quickly daft jumping zebras vex.&#39;</span><span class="p">)</span>

  488. <span class="n">logger2</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;Jail zesty vixen who grabbed pay from quack.&#39;</span><span class="p">)</span>

  489. <span class="n">logger2</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;The five boxing wizards jump quickly.&#39;</span><span class="p">)</span>

  490. </pre></div>

  491. </div>

  492. <p>When you run this, on the console you will see</p>

  493. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>root        : INFO     Jackdaws love my big sphinx of quartz.

  494. myapp.area1 : INFO     How quickly daft jumping zebras vex.

  495. myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.

  496. myapp.area2 : ERROR    The five boxing wizards jump quickly.

  497. </pre></div>

  498. </div>

  499. <p>and in the file you will see something like</p>

  500. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.

  501. 10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.

  502. 10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.

  503. 10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.

  504. 10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly.

  505. </pre></div>

  506. </div>

  507. <p>As you can see, the DEBUG message only shows up in the file. The other messages

  508. are sent to both destinations.</p>

  509. <p>This example uses console and file handlers, but you can use any number and

  510. combination of handlers you choose.</p>

  511. <p>Note that the above choice of log filename <code class="docutils literal notranslate"><span class="pre">/tmp/myapp.log</span></code> implies use of a

  512. standard location for temporary files on POSIX systems. On Windows, you may need to

  513. choose a different directory name for the log - just ensure that the directory exists

  514. and that you have the permissions to create and update files in it.</p>

  515. </section>

  516. <section id="custom-handling-of-levels">

  517. <span id="custom-level-handling"></span><h2>Custom handling of levels<a class="headerlink" href="#custom-handling-of-levels" title="Link to this heading">¶</a></h2>

  518. <p>Sometimes, you might want to do something slightly different from the standard

  519. handling of levels in handlers, where all levels above a threshold get

  520. processed by a handler. To do this, you need to use filters. Let’s look at a

  521. scenario where you want to arrange things as follows:</p>

  522. <ul class="simple">

  523. <li><p>Send messages of severity <code class="docutils literal notranslate"><span class="pre">INFO</span></code> and <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> to <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code></p></li>

  524. <li><p>Send messages of severity <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> and above to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code></p></li>

  525. <li><p>Send messages of severity <code class="docutils literal notranslate"><span class="pre">DEBUG</span></code> and above to file <code class="docutils literal notranslate"><span class="pre">app.log</span></code></p></li>

  526. </ul>

  527. <p>Suppose you configure logging with the following JSON:</p>

  528. <div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>

  529. <span class="w">    </span><span class="nt">&quot;version&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>

  530. <span class="w">    </span><span class="nt">&quot;disable_existing_loggers&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>

  531. <span class="w">    </span><span class="nt">&quot;formatters&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  532. <span class="w">        </span><span class="nt">&quot;simple&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  533. <span class="w">            </span><span class="nt">&quot;format&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;%(levelname)-8s - %(message)s&quot;</span>

  534. <span class="w">        </span><span class="p">}</span>

  535. <span class="w">    </span><span class="p">},</span>

  536. <span class="w">    </span><span class="nt">&quot;handlers&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  537. <span class="w">        </span><span class="nt">&quot;stdout&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  538. <span class="w">            </span><span class="nt">&quot;class&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;logging.StreamHandler&quot;</span><span class="p">,</span>

  539. <span class="w">            </span><span class="nt">&quot;level&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;INFO&quot;</span><span class="p">,</span>

  540. <span class="w">            </span><span class="nt">&quot;formatter&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;simple&quot;</span><span class="p">,</span>

  541. <span class="w">            </span><span class="nt">&quot;stream&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ext://sys.stdout&quot;</span>

  542. <span class="w">        </span><span class="p">},</span>

  543. <span class="w">        </span><span class="nt">&quot;stderr&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  544. <span class="w">            </span><span class="nt">&quot;class&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;logging.StreamHandler&quot;</span><span class="p">,</span>

  545. <span class="w">            </span><span class="nt">&quot;level&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ERROR&quot;</span><span class="p">,</span>

  546. <span class="w">            </span><span class="nt">&quot;formatter&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;simple&quot;</span><span class="p">,</span>

  547. <span class="w">            </span><span class="nt">&quot;stream&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ext://sys.stderr&quot;</span>

  548. <span class="w">        </span><span class="p">},</span>

  549. <span class="w">        </span><span class="nt">&quot;file&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  550. <span class="w">            </span><span class="nt">&quot;class&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;logging.FileHandler&quot;</span><span class="p">,</span>

  551. <span class="w">            </span><span class="nt">&quot;formatter&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;simple&quot;</span><span class="p">,</span>

  552. <span class="w">            </span><span class="nt">&quot;filename&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;app.log&quot;</span><span class="p">,</span>

  553. <span class="w">            </span><span class="nt">&quot;mode&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;w&quot;</span>

  554. <span class="w">        </span><span class="p">}</span>

  555. <span class="w">    </span><span class="p">},</span>

  556. <span class="w">    </span><span class="nt">&quot;root&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  557. <span class="w">        </span><span class="nt">&quot;level&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;DEBUG&quot;</span><span class="p">,</span>

  558. <span class="w">        </span><span class="nt">&quot;handlers&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>

  559. <span class="w">            </span><span class="s2">&quot;stderr&quot;</span><span class="p">,</span>

  560. <span class="w">            </span><span class="s2">&quot;stdout&quot;</span><span class="p">,</span>

  561. <span class="w">            </span><span class="s2">&quot;file&quot;</span>

  562. <span class="w">        </span><span class="p">]</span>

  563. <span class="w">    </span><span class="p">}</span>

  564. <span class="p">}</span>

  565. </pre></div>

  566. </div>

  567. <p>This configuration does <em>almost</em> what we want, except that <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> would

  568. show messages of severity <code class="docutils literal notranslate"><span class="pre">ERROR</span></code> and above as well as <code class="docutils literal notranslate"><span class="pre">INFO</span></code> and

  569. <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> messages. To prevent this, we can set up a filter which excludes

  570. those messages and add it to the relevant handler. This can be configured by

  571. adding a <code class="docutils literal notranslate"><span class="pre">filters</span></code> section parallel to <code class="docutils literal notranslate"><span class="pre">formatters</span></code> and <code class="docutils literal notranslate"><span class="pre">handlers</span></code>:</p>

  572. <div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>

  573. <span class="w">    </span><span class="nt">&quot;filters&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  574. <span class="w">        </span><span class="nt">&quot;warnings_and_below&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  575. <span class="w">            </span><span class="nt">&quot;()&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;__main__.filter_maker&quot;</span><span class="p">,</span>

  576. <span class="w">            </span><span class="nt">&quot;level&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;WARNING&quot;</span>

  577. <span class="w">        </span><span class="p">}</span>

  578. <span class="w">    </span><span class="p">}</span>

  579. <span class="p">}</span>

  580. </pre></div>

  581. </div>

  582. <p>and changing the section on the <code class="docutils literal notranslate"><span class="pre">stdout</span></code> handler to add it:</p>

  583. <div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>

  584. <span class="w">    </span><span class="nt">&quot;stdout&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>

  585. <span class="w">        </span><span class="nt">&quot;class&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;logging.StreamHandler&quot;</span><span class="p">,</span>

  586. <span class="w">        </span><span class="nt">&quot;level&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;INFO&quot;</span><span class="p">,</span>

  587. <span class="w">        </span><span class="nt">&quot;formatter&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;simple&quot;</span><span class="p">,</span>

  588. <span class="w">        </span><span class="nt">&quot;stream&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ext://sys.stdout&quot;</span><span class="p">,</span>

  589. <span class="w">        </span><span class="nt">&quot;filters&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&quot;warnings_and_below&quot;</span><span class="p">]</span>

  590. <span class="w">    </span><span class="p">}</span>

  591. <span class="p">}</span>

  592. </pre></div>

  593. </div>

  594. <p>A filter is just a function, so we can define the <code class="docutils literal notranslate"><span class="pre">filter_maker</span></code> (a factory

  595. function) as follows:</p>

  596. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">filter_maker</span><span class="p">(</span><span class="n">level</span><span class="p">):</span>

  597.     <span class="n">level</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">logging</span><span class="p">,</span> <span class="n">level</span><span class="p">)</span>

  598. 

  599.     <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">record</span><span class="p">):</span>

  600.         <span class="k">return</span> <span class="n">record</span><span class="o">.</span><span class="n">levelno</span> <span class="o">&lt;=</span> <span class="n">level</span>

  601. 

  602.     <span class="k">return</span> <span class="nb">filter</span>

  603. </pre></div>

  604. </div>

  605. <p>This converts the string argument passed in to a numeric level, and returns a

  606. function which only returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the level of the passed in record is

  607. at or below the specified level. Note that in this example I have defined the

  608. <code class="docutils literal notranslate"><span class="pre">filter_maker</span></code> in a test script <code class="docutils literal notranslate"><span class="pre">main.py</span></code> that I run from the command line,

  609. so its module will be <code class="docutils literal notranslate"><span class="pre">__main__</span></code> - hence the <code class="docutils literal notranslate"><span class="pre">__main__.filter_maker</span></code> in the

  610. filter configuration. You will need to change that if you define it in a

  611. different module.</p>

  612. <p>With the filter added, we can run <code class="docutils literal notranslate"><span class="pre">main.py</span></code>, which in full is:</p>

  613. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">json</span>

  614. <span class="kn">import</span> <span class="nn">logging</span>

  615. <span class="kn">import</span> <span class="nn">logging.config</span>

  616. 

  617. <span class="n">CONFIG</span> <span class="o">=</span> <span class="s1">&#39;&#39;&#39;</span>

  618. <span class="s1">{</span>

  619. <span class="s1">    &quot;version&quot;: 1,</span>

  620. <span class="s1">    &quot;disable_existing_loggers&quot;: false,</span>

  621. <span class="s1">    &quot;formatters&quot;: {</span>

  622. <span class="s1">        &quot;simple&quot;: {</span>

  623. <span class="s1">            &quot;format&quot;: &quot;</span><span class="si">%(levelname)-8s</span><span class="s1"> - </span><span class="si">%(message)s</span><span class="s1">&quot;</span>

  624. <span class="s1">        }</span>

  625. <span class="s1">    },</span>

  626. <span class="s1">    &quot;filters&quot;: {</span>

  627. <span class="s1">        &quot;warnings_and_below&quot;: {</span>

  628. <span class="s1">            &quot;()&quot; : &quot;__main__.filter_maker&quot;,</span>

  629. <span class="s1">            &quot;level&quot;: &quot;WARNING&quot;</span>

  630. <span class="s1">        }</span>

  631. <span class="s1">    },</span>

  632. <span class="s1">    &quot;handlers&quot;: {</span>

  633. <span class="s1">        &quot;stdout&quot;: {</span>

  634. <span class="s1">            &quot;class&quot;: &quot;logging.StreamHandler&quot;,</span>

  635. <span class="s1">            &quot;level&quot;: &quot;INFO&quot;,</span>

  636. <span class="s1">            &quot;formatter&quot;: &quot;simple&quot;,</span>

  637. <span class="s1">            &quot;stream&quot;: &quot;ext://sys.stdout&quot;,</span>

  638. <span class="s1">            &quot;filters&quot;: [&quot;warnings_and_below&quot;]</span>

  639. <span class="s1">        },</span>

  640. <span class="s1">        &quot;stderr&quot;: {</span>

  641. <span class="s1">            &quot;class&quot;: &quot;logging.StreamHandler&quot;,</span>

  642. <span class="s1">            &quot;level&quot;: &quot;ERROR&quot;,</span>

  643. <span class="s1">            &quot;formatter&quot;: &quot;simple&quot;,</span>

  644. <span class="s1">            &quot;stream&quot;: &quot;ext://sys.stderr&quot;</span>

  645. <span class="s1">        },</span>

  646. <span class="s1">        &quot;file&quot;: {</span>

  647. <span class="s1">            &quot;class&quot;: &quot;logging.FileHandler&quot;,</span>

  648. <span class="s1">            &quot;formatter&quot;: &quot;simple&quot;,</span>

  649. <span class="s1">            &quot;filename&quot;: &quot;app.log&quot;,</span>

  650. <span class="s1">            &quot;mode&quot;: &quot;w&quot;</span>

  651. <span class="s1">        }</span>

  652. <span class="s1">    },</span>

  653. <span class="s1">    &quot;root&quot;: {</span>

  654. <span class="s1">        &quot;level&quot;: &quot;DEBUG&quot;,</span>

  655. <span class="s1">        &quot;handlers&quot;: [</span>

  656. <span class="s1">            &quot;stderr&quot;,</span>

  657. <span class="s1">            &quot;stdout&quot;,</span>

  658. <span class="s1">            &quot;file&quot;</span>

  659. <span class="s1">        ]</span>

  660. <span class="s1">    }</span>

  661. <span class="s1">}</span>

  662. <span class="s1">&#39;&#39;&#39;</span>

  663. 

  664. <span class="k">def</span> <span class="nf">filter_maker</span><span class="p">(</span><span class="n">level</span><span class="p">):</span>

  665.     <span class="n">level</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">logging</span><span class="p">,</span> <span class="n">level</span><span class="p">)</span>

  666. 

  667.     <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">record</span><span class="p">):</span>

  668.         <span class="k">return</span> <span class="n">record</span><span class="o">.</span><span class="n">levelno</span> <span class="o">&lt;=</span> <span class="n">level</span>

  669. 

  670.     <span class="k">return</span> <span class="nb">filter</span>

  671. 

  672. <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">CONFIG</span><span class="p">))</span>

  673. <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;A DEBUG message&#39;</span><span class="p">)</span>

  674. <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;An INFO message&#39;</span><span class="p">)</span>

  675. <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;A WARNING message&#39;</span><span class="p">)</span>

  676. <span class="n">logging</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;An ERROR message&#39;</span><span class="p">)</span>

  677. <span class="n">logging</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;A CRITICAL message&#39;</span><span class="p">)</span>

  678. </pre></div>

  679. </div>

  680. <p>And after running it like this:</p>

  681. <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>main.py<span class="w"> </span><span class="m">2</span>&gt;stderr.log<span class="w"> </span>&gt;stdout.log

  682. </pre></div>

  683. </div>

  684. <p>We can see the results are as expected:</p>

  685. <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>more<span class="w"> </span>*.log

  686. ::::::::::::::

  687. app.log

  688. ::::::::::::::

  689. DEBUG<span class="w">    </span>-<span class="w"> </span>A<span class="w"> </span>DEBUG<span class="w"> </span>message

  690. INFO<span class="w">     </span>-<span class="w"> </span>An<span class="w"> </span>INFO<span class="w"> </span>message

  691. WARNING<span class="w">  </span>-<span class="w"> </span>A<span class="w"> </span>WARNING<span class="w"> </span>message

  692. ERROR<span class="w">    </span>-<span class="w"> </span>An<span class="w"> </span>ERROR<span class="w"> </span>message

  693. CRITICAL<span class="w"> </span>-<span class="w"> </span>A<span class="w"> </span>CRITICAL<span class="w"> </span>message

  694. ::::::::::::::

  695. stderr.log

  696. ::::::::::::::

  697. ERROR<span class="w">    </span>-<span class="w"> </span>An<span class="w"> </span>ERROR<span class="w"> </span>message

  698. CRITICAL<span class="w"> </span>-<span class="w"> </span>A<span class="w"> </span>CRITICAL<span class="w"> </span>message

  699. ::::::::::::::

  700. stdout.log

  701. ::::::::::::::

  702. INFO<span class="w">     </span>-<span class="w"> </span>An<span class="w"> </span>INFO<span class="w"> </span>message

  703. WARNING<span class="w">  </span>-<span class="w"> </span>A<span class="w"> </span>WARNING<span class="w"> </span>message

  704. </pre></div>

  705. </div>

  706. </section>

  707. <section id="configuration-server-example">

  708. <h2>Configuration server example<a class="headerlink" href="#configuration-server-example" title="Link to this heading">¶</a></h2>

  709. <p>Here is an example of a module using the logging configuration server:</p>

  710. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  711. <span class="kn">import</span> <span class="nn">logging.config</span>

  712. <span class="kn">import</span> <span class="nn">time</span>

  713. <span class="kn">import</span> <span class="nn">os</span>

  714. 

  715. <span class="c1"># read initial config file</span>

  716. <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">fileConfig</span><span class="p">(</span><span class="s1">&#39;logging.conf&#39;</span><span class="p">)</span>

  717. 

  718. <span class="c1"># create and start listener on port 9999</span>

  719. <span class="n">t</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="mi">9999</span><span class="p">)</span>

  720. <span class="n">t</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  721. 

  722. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;simpleExample&#39;</span><span class="p">)</span>

  723. 

  724. <span class="k">try</span><span class="p">:</span>

  725.     <span class="c1"># loop through logging calls to see the difference</span>

  726.     <span class="c1"># new configurations make, until Ctrl+C is pressed</span>

  727.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  728.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;debug message&#39;</span><span class="p">)</span>

  729.         <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;info message&#39;</span><span class="p">)</span>

  730.         <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;warn message&#39;</span><span class="p">)</span>

  731.         <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;error message&#39;</span><span class="p">)</span>

  732.         <span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;critical message&#39;</span><span class="p">)</span>

  733.         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>

  734. <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>

  735.     <span class="c1"># cleanup</span>

  736.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">stopListening</span><span class="p">()</span>

  737.     <span class="n">t</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  738. </pre></div>

  739. </div>

  740. <p>And here is a script that takes a filename and sends that file to the server,

  741. properly preceded with the binary-encoded length, as the new logging

  742. configuration:</p>

  743. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>

  744. <span class="kn">import</span> <span class="nn">socket</span><span class="o">,</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">struct</span>

  745. 

  746. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  747.     <span class="n">data_to_send</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>

  748. 

  749. <span class="n">HOST</span> <span class="o">=</span> <span class="s1">&#39;localhost&#39;</span>

  750. <span class="n">PORT</span> <span class="o">=</span> <span class="mi">9999</span>

  751. <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">)</span>

  752. <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;connecting...&#39;</span><span class="p">)</span>

  753. <span class="n">s</span><span class="o">.</span><span class="n">connect</span><span class="p">((</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">))</span>

  754. <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;sending config...&#39;</span><span class="p">)</span>

  755. <span class="n">s</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">pack</span><span class="p">(</span><span class="s1">&#39;&gt;L&#39;</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">data_to_send</span><span class="p">)))</span>

  756. <span class="n">s</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">data_to_send</span><span class="p">)</span>

  757. <span class="n">s</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  758. <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;complete&#39;</span><span class="p">)</span>

  759. </pre></div>

  760. </div>

  761. </section>

  762. <section id="dealing-with-handlers-that-block">

  763. <span id="blocking-handlers"></span><h2>Dealing with handlers that block<a class="headerlink" href="#dealing-with-handlers-that-block" title="Link to this heading">¶</a></h2>

  764. <p>Sometimes you have to get your logging handlers to do their work without

  765. blocking the thread you’re logging from. This is common in web applications,

  766. though of course it also occurs in other scenarios.</p>

  767. <p>A common culprit which demonstrates sluggish behaviour is the

  768. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SMTPHandler" title="logging.handlers.SMTPHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SMTPHandler</span></code></a>: sending emails can take a long time, for a

  769. number of reasons outside the developer’s control (for example, a poorly

  770. performing mail or network infrastructure). But almost any network-based

  771. handler can block: Even a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler" title="logging.handlers.SocketHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SocketHandler</span></code></a> operation may do a

  772. DNS query under the hood which is too slow (and this query can be deep in the

  773. socket library code, below the Python layer, and outside your control).</p>

  774. <p>One solution is to use a two-part approach. For the first part, attach only a

  775. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueHandler" title="logging.handlers.QueueHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueHandler</span></code></a> to those loggers which are accessed from

  776. performance-critical threads. They simply write to their queue, which can be

  777. sized to a large enough capacity or initialized with no upper bound to their

  778. size. The write to the queue will typically be accepted quickly, though you

  779. will probably need to catch the <a class="reference internal" href="../library/queue.html#queue.Full" title="queue.Full"><code class="xref py py-exc docutils literal notranslate"><span class="pre">queue.Full</span></code></a> exception as a precaution

  780. in your code. If you are a library developer who has performance-critical

  781. threads in their code, be sure to document this (together with a suggestion to

  782. attach only <code class="docutils literal notranslate"><span class="pre">QueueHandlers</span></code> to your loggers) for the benefit of other

  783. developers who will use your code.</p>

  784. <p>The second part of the solution is <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueListener" title="logging.handlers.QueueListener"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueListener</span></code></a>, which has been

  785. designed as the counterpart to <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueHandler" title="logging.handlers.QueueHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueHandler</span></code></a>.  A

  786. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueListener" title="logging.handlers.QueueListener"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueListener</span></code></a> is very simple: it’s passed a queue and some handlers,

  787. and it fires up an internal thread which listens to its queue for LogRecords

  788. sent from <code class="docutils literal notranslate"><span class="pre">QueueHandlers</span></code> (or any other source of <code class="docutils literal notranslate"><span class="pre">LogRecords</span></code>, for that

  789. matter). The <code class="docutils literal notranslate"><span class="pre">LogRecords</span></code> are removed from the queue and passed to the

  790. handlers for processing.</p>

  791. <p>The advantage of having a separate <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueListener" title="logging.handlers.QueueListener"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueListener</span></code></a> class is that you

  792. can use the same instance to service multiple <code class="docutils literal notranslate"><span class="pre">QueueHandlers</span></code>. This is more

  793. resource-friendly than, say, having threaded versions of the existing handler

  794. classes, which would eat up one thread per handler for no particular benefit.</p>

  795. <p>An example of using these two classes follows (imports omitted):</p>

  796. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">que</span> <span class="o">=</span> <span class="n">queue</span><span class="o">.</span><span class="n">Queue</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>  <span class="c1"># no limit on size</span>

  797. <span class="n">queue_handler</span> <span class="o">=</span> <span class="n">QueueHandler</span><span class="p">(</span><span class="n">que</span><span class="p">)</span>

  798. <span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  799. <span class="n">listener</span> <span class="o">=</span> <span class="n">QueueListener</span><span class="p">(</span><span class="n">que</span><span class="p">,</span> <span class="n">handler</span><span class="p">)</span>

  800. <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  801. <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">queue_handler</span><span class="p">)</span>

  802. <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(threadName)s</span><span class="s1">: </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  803. <span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  804. <span class="n">listener</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  805. <span class="c1"># The log output will display the thread which generated</span>

  806. <span class="c1"># the event (the main thread) rather than the internal</span>

  807. <span class="c1"># thread which monitors the internal queue. This is what</span>

  808. <span class="c1"># you want to happen.</span>

  809. <span class="n">root</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;Look out!&#39;</span><span class="p">)</span>

  810. <span class="n">listener</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>

  811. </pre></div>

  812. </div>

  813. <p>which, when run, will produce:</p>

  814. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>MainThread: Look out!

  815. </pre></div>

  816. </div>

  817. <div class="admonition note">

  818. <p class="admonition-title">Note</p>

  819. <p>Although the earlier discussion wasn’t specifically talking about

  820. async code, but rather about slow logging handlers, it should be noted that

  821. when logging from async code, network and even file handlers could lead to

  822. problems (blocking the event loop) because some logging is done from

  823. <a class="reference internal" href="../library/asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> internals. It might be best, if any async code is used in an

  824. application, to use the above approach for logging, so that any blocking code

  825. runs only in the <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code> thread.</p>

  826. </div>

  827. <div class="versionchanged">

  828. <p><span class="versionmodified changed">Changed in version 3.5: </span>Prior to Python 3.5, the <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueListener" title="logging.handlers.QueueListener"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueListener</span></code></a> always passed every message

  829. received from the queue to every handler it was initialized with. (This was

  830. because it was assumed that level filtering was all done on the other side,

  831. where the queue is filled.) From 3.5 onwards, this behaviour can be changed

  832. by passing a keyword argument <code class="docutils literal notranslate"><span class="pre">respect_handler_level=True</span></code> to the

  833. listener’s constructor. When this is done, the listener compares the level

  834. of each message with the handler’s level, and only passes a message to a

  835. handler if it’s appropriate to do so.</p>

  836. </div>

  837. </section>

  838. <section id="sending-and-receiving-logging-events-across-a-network">

  839. <span id="network-logging"></span><h2>Sending and receiving logging events across a network<a class="headerlink" href="#sending-and-receiving-logging-events-across-a-network" title="Link to this heading">¶</a></h2>

  840. <p>Let’s say you want to send logging events across a network, and handle them at

  841. the receiving end. A simple way of doing this is attaching a

  842. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler" title="logging.handlers.SocketHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SocketHandler</span></code></a> instance to the root logger at the sending end:</p>

  843. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span><span class="o">,</span> <span class="nn">logging.handlers</span>

  844. 

  845. <span class="n">rootLogger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">)</span>

  846. <span class="n">rootLogger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  847. <span class="n">socketHandler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">SocketHandler</span><span class="p">(</span><span class="s1">&#39;localhost&#39;</span><span class="p">,</span>

  848.                     <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">DEFAULT_TCP_LOGGING_PORT</span><span class="p">)</span>

  849. <span class="c1"># don&#39;t bother with a formatter, since a socket handler sends the event as</span>

  850. <span class="c1"># an unformatted pickle</span>

  851. <span class="n">rootLogger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">socketHandler</span><span class="p">)</span>

  852. 

  853. <span class="c1"># Now, we can log to the root logger, or any other logger. First the root...</span>

  854. <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Jackdaws love my big sphinx of quartz.&#39;</span><span class="p">)</span>

  855. 

  856. <span class="c1"># Now, define a couple of other loggers which might represent areas in your</span>

  857. <span class="c1"># application:</span>

  858. 

  859. <span class="n">logger1</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;myapp.area1&#39;</span><span class="p">)</span>

  860. <span class="n">logger2</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;myapp.area2&#39;</span><span class="p">)</span>

  861. 

  862. <span class="n">logger1</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Quick zephyrs blow, vexing daft Jim.&#39;</span><span class="p">)</span>

  863. <span class="n">logger1</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;How quickly daft jumping zebras vex.&#39;</span><span class="p">)</span>

  864. <span class="n">logger2</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;Jail zesty vixen who grabbed pay from quack.&#39;</span><span class="p">)</span>

  865. <span class="n">logger2</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;The five boxing wizards jump quickly.&#39;</span><span class="p">)</span>

  866. </pre></div>

  867. </div>

  868. <p>At the receiving end, you can set up a receiver using the <a class="reference internal" href="../library/socketserver.html#module-socketserver" title="socketserver: A framework for network servers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socketserver</span></code></a>

  869. module. Here is a basic working example:</p>

  870. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pickle</span>

  871. <span class="kn">import</span> <span class="nn">logging</span>

  872. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  873. <span class="kn">import</span> <span class="nn">socketserver</span>

  874. <span class="kn">import</span> <span class="nn">struct</span>

  875. 

  876. 

  877. <span class="k">class</span> <span class="nc">LogRecordStreamHandler</span><span class="p">(</span><span class="n">socketserver</span><span class="o">.</span><span class="n">StreamRequestHandler</span><span class="p">):</span>

  878. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Handler for a streaming logging request.</span>

  879. 

  880. <span class="sd">    This basically logs the record using whatever logging policy is</span>

  881. <span class="sd">    configured locally.</span>

  882. <span class="sd">    &quot;&quot;&quot;</span>

  883. 

  884.     <span class="k">def</span> <span class="nf">handle</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  885. <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>

  886. <span class="sd">        Handle multiple requests - each expected to be a 4-byte length,</span>

  887. <span class="sd">        followed by the LogRecord in pickle format. Logs the record</span>

  888. <span class="sd">        according to whatever policy is configured locally.</span>

  889. <span class="sd">        &quot;&quot;&quot;</span>

  890.         <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  891.             <span class="n">chunk</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>

  892.             <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">4</span><span class="p">:</span>

  893.                 <span class="k">break</span>

  894.             <span class="n">slen</span> <span class="o">=</span> <span class="n">struct</span><span class="o">.</span><span class="n">unpack</span><span class="p">(</span><span class="s1">&#39;&gt;L&#39;</span><span class="p">,</span> <span class="n">chunk</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>

  895.             <span class="n">chunk</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="n">slen</span><span class="p">)</span>

  896.             <span class="k">while</span> <span class="nb">len</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">slen</span><span class="p">:</span>

  897.                 <span class="n">chunk</span> <span class="o">=</span> <span class="n">chunk</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="n">slen</span> <span class="o">-</span> <span class="nb">len</span><span class="p">(</span><span class="n">chunk</span><span class="p">))</span>

  898.             <span class="n">obj</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">unPickle</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span>

  899.             <span class="n">record</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">makeLogRecord</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>

  900.             <span class="bp">self</span><span class="o">.</span><span class="n">handleLogRecord</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  901. 

  902.     <span class="k">def</span> <span class="nf">unPickle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>

  903.         <span class="k">return</span> <span class="n">pickle</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>

  904. 

  905.     <span class="k">def</span> <span class="nf">handleLogRecord</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  906.         <span class="c1"># if a name is specified, we use the named logger rather than the one</span>

  907.         <span class="c1"># implied by the record.</span>

  908.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">logname</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  909.             <span class="n">name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">logname</span>

  910.         <span class="k">else</span><span class="p">:</span>

  911.             <span class="n">name</span> <span class="o">=</span> <span class="n">record</span><span class="o">.</span><span class="n">name</span>

  912.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>

  913.         <span class="c1"># N.B. EVERY record gets logged. This is because Logger.handle</span>

  914.         <span class="c1"># is normally called AFTER logger-level filtering. If you want</span>

  915.         <span class="c1"># to do filtering, do it at the client end to save wasting</span>

  916.         <span class="c1"># cycles and network bandwidth!</span>

  917.         <span class="n">logger</span><span class="o">.</span><span class="n">handle</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  918. 

  919. <span class="k">class</span> <span class="nc">LogRecordSocketReceiver</span><span class="p">(</span><span class="n">socketserver</span><span class="o">.</span><span class="n">ThreadingTCPServer</span><span class="p">):</span>

  920. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  921. <span class="sd">    Simple TCP socket-based logging receiver suitable for testing.</span>

  922. <span class="sd">    &quot;&quot;&quot;</span>

  923. 

  924.     <span class="n">allow_reuse_address</span> <span class="o">=</span> <span class="kc">True</span>

  925. 

  926.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s1">&#39;localhost&#39;</span><span class="p">,</span>

  927.                  <span class="n">port</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">DEFAULT_TCP_LOGGING_PORT</span><span class="p">,</span>

  928.                  <span class="n">handler</span><span class="o">=</span><span class="n">LogRecordStreamHandler</span><span class="p">):</span>

  929.         <span class="n">socketserver</span><span class="o">.</span><span class="n">ThreadingTCPServer</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="p">),</span> <span class="n">handler</span><span class="p">)</span>

  930.         <span class="bp">self</span><span class="o">.</span><span class="n">abort</span> <span class="o">=</span> <span class="mi">0</span>

  931.         <span class="bp">self</span><span class="o">.</span><span class="n">timeout</span> <span class="o">=</span> <span class="mi">1</span>

  932.         <span class="bp">self</span><span class="o">.</span><span class="n">logname</span> <span class="o">=</span> <span class="kc">None</span>

  933. 

  934.     <span class="k">def</span> <span class="nf">serve_until_stopped</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  935.         <span class="kn">import</span> <span class="nn">select</span>

  936.         <span class="n">abort</span> <span class="o">=</span> <span class="mi">0</span>

  937.         <span class="k">while</span> <span class="ow">not</span> <span class="n">abort</span><span class="p">:</span>

  938.             <span class="n">rd</span><span class="p">,</span> <span class="n">wr</span><span class="p">,</span> <span class="n">ex</span> <span class="o">=</span> <span class="n">select</span><span class="o">.</span><span class="n">select</span><span class="p">([</span><span class="bp">self</span><span class="o">.</span><span class="n">socket</span><span class="o">.</span><span class="n">fileno</span><span class="p">()],</span>

  939.                                        <span class="p">[],</span> <span class="p">[],</span>

  940.                                        <span class="bp">self</span><span class="o">.</span><span class="n">timeout</span><span class="p">)</span>

  941.             <span class="k">if</span> <span class="n">rd</span><span class="p">:</span>

  942.                 <span class="bp">self</span><span class="o">.</span><span class="n">handle_request</span><span class="p">()</span>

  943.             <span class="n">abort</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">abort</span>

  944. 

  945. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  946.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span>

  947.         <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(relativeCreated)5d</span><span class="s1"> </span><span class="si">%(name)-15s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  948.     <span class="n">tcpserver</span> <span class="o">=</span> <span class="n">LogRecordSocketReceiver</span><span class="p">()</span>

  949.     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;About to start TCP server...&#39;</span><span class="p">)</span>

  950.     <span class="n">tcpserver</span><span class="o">.</span><span class="n">serve_until_stopped</span><span class="p">()</span>

  951. 

  952. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  953.     <span class="n">main</span><span class="p">()</span>

  954. </pre></div>

  955. </div>

  956. <p>First run the server, and then the client. On the client side, nothing is

  957. printed on the console; on the server side, you should see something like:</p>

  958. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>About to start TCP server...

  959.    59 root            INFO     Jackdaws love my big sphinx of quartz.

  960.    59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.

  961.    69 myapp.area1     INFO     How quickly daft jumping zebras vex.

  962.    69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.

  963.    69 myapp.area2     ERROR    The five boxing wizards jump quickly.

  964. </pre></div>

  965. </div>

  966. <p>Note that there are some security issues with pickle in some scenarios. If

  967. these affect you, you can use an alternative serialization scheme by overriding

  968. the <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler.makePickle" title="logging.handlers.SocketHandler.makePickle"><code class="xref py py-meth docutils literal notranslate"><span class="pre">makePickle()</span></code></a> method and implementing your

  969. alternative there, as well as adapting the above script to use your alternative

  970. serialization.</p>

  971. <section id="running-a-logging-socket-listener-in-production">

  972. <h3>Running a logging socket listener in production<a class="headerlink" href="#running-a-logging-socket-listener-in-production" title="Link to this heading">¶</a></h3>

  973. <p>To run a logging listener in production, you may need to use a

  974. process-management tool such as <a class="reference external" href="http://supervisord.org/">Supervisor</a>.

  975. <a class="reference external" href="https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b">Here is a Gist</a>

  976. which provides the bare-bones files to run the above functionality using

  977. Supervisor. It consists of the following files:</p>

  978. <table class="docutils align-default">

  979. <thead>

  980. <tr class="row-odd"><th class="head"><p>File</p></th>

  981. <th class="head"><p>Purpose</p></th>

  982. </tr>

  983. </thead>

  984. <tbody>

  985. <tr class="row-even"><td><p><code class="file docutils literal notranslate"><span class="pre">prepare.sh</span></code></p></td>

  986. <td><p>A Bash script to prepare the environment for

  987. testing</p></td>

  988. </tr>

  989. <tr class="row-odd"><td><p><code class="file docutils literal notranslate"><span class="pre">supervisor.conf</span></code></p></td>

  990. <td><p>The Supervisor configuration file, which has

  991. entries for the listener and a multi-process web

  992. application</p></td>

  993. </tr>

  994. <tr class="row-even"><td><p><code class="file docutils literal notranslate"><span class="pre">ensure_app.sh</span></code></p></td>

  995. <td><p>A Bash script to ensure that Supervisor is running

  996. with the above configuration</p></td>

  997. </tr>

  998. <tr class="row-odd"><td><p><code class="file docutils literal notranslate"><span class="pre">log_listener.py</span></code></p></td>

  999. <td><p>The socket listener program which receives log

  1000. events and records them to a file</p></td>

  1001. </tr>

  1002. <tr class="row-even"><td><p><code class="file docutils literal notranslate"><span class="pre">main.py</span></code></p></td>

  1003. <td><p>A simple web application which performs logging

  1004. via a socket connected to the listener</p></td>

  1005. </tr>

  1006. <tr class="row-odd"><td><p><code class="file docutils literal notranslate"><span class="pre">webapp.json</span></code></p></td>

  1007. <td><p>A JSON configuration file for the web application</p></td>

  1008. </tr>

  1009. <tr class="row-even"><td><p><code class="file docutils literal notranslate"><span class="pre">client.py</span></code></p></td>

  1010. <td><p>A Python script to exercise the web application</p></td>

  1011. </tr>

  1012. </tbody>

  1013. </table>

  1014. <p>The web application uses <a class="reference external" href="https://gunicorn.org/">Gunicorn</a>, which is a

  1015. popular web application server that starts multiple worker processes to handle

  1016. requests. This example setup shows how the workers can write to the same log file

  1017. without conflicting with one another — they all go through the socket listener.</p>

  1018. <p>To test these files, do the following in a POSIX environment:</p>

  1019. <ol class="arabic simple">

  1020. <li><p>Download <a class="reference external" href="https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b">the Gist</a>

  1021. as a ZIP archive using the <span class="guilabel">Download ZIP</span> button.</p></li>

  1022. <li><p>Unzip the above files from the archive into a scratch directory.</p></li>

  1023. <li><p>In the scratch directory, run <code class="docutils literal notranslate"><span class="pre">bash</span> <span class="pre">prepare.sh</span></code> to get things ready.

  1024. This creates a <code class="file docutils literal notranslate"><span class="pre">run</span></code> subdirectory to contain Supervisor-related and

  1025. log files, and a <code class="file docutils literal notranslate"><span class="pre">venv</span></code> subdirectory to contain a virtual environment

  1026. into which <code class="docutils literal notranslate"><span class="pre">bottle</span></code>, <code class="docutils literal notranslate"><span class="pre">gunicorn</span></code> and <code class="docutils literal notranslate"><span class="pre">supervisor</span></code> are installed.</p></li>

  1027. <li><p>Run <code class="docutils literal notranslate"><span class="pre">bash</span> <span class="pre">ensure_app.sh</span></code> to ensure that Supervisor is running with

  1028. the above configuration.</p></li>

  1029. <li><p>Run <code class="docutils literal notranslate"><span class="pre">venv/bin/python</span> <span class="pre">client.py</span></code> to exercise the web application,

  1030. which will lead to records being written to the log.</p></li>

  1031. <li><p>Inspect the log files in the <code class="file docutils literal notranslate"><span class="pre">run</span></code> subdirectory. You should see the

  1032. most recent log lines in files matching the pattern <code class="file docutils literal notranslate"><span class="pre">app.log*</span></code>. They won’t be in

  1033. any particular order, since they have been handled concurrently by different

  1034. worker processes in a non-deterministic way.</p></li>

  1035. <li><p>You can shut down the listener and the web application by running

  1036. <code class="docutils literal notranslate"><span class="pre">venv/bin/supervisorctl</span> <span class="pre">-c</span> <span class="pre">supervisor.conf</span> <span class="pre">shutdown</span></code>.</p></li>

  1037. </ol>

  1038. <p>You may need to tweak the configuration files in the unlikely event that the

  1039. configured ports clash with something else in your test environment.</p>

  1040. </section>

  1041. </section>

  1042. <section id="adding-contextual-information-to-your-logging-output">

  1043. <span id="context-info"></span><h2>Adding contextual information to your logging output<a class="headerlink" href="#adding-contextual-information-to-your-logging-output" title="Link to this heading">¶</a></h2>

  1044. <p>Sometimes you want logging output to contain contextual information in

  1045. addition to the parameters passed to the logging call. For example, in a

  1046. networked application, it may be desirable to log client-specific information

  1047. in the log (e.g. remote client’s username, or IP address). Although you could

  1048. use the <em>extra</em> parameter to achieve this, it’s not always convenient to pass

  1049. the information in this way. While it might be tempting to create

  1050. <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> instances on a per-connection basis, this is not a good idea

  1051. because these instances are not garbage collected. While this is not a problem

  1052. in practice, when the number of <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> instances is dependent on the

  1053. level of granularity you want to use in logging an application, it could

  1054. be hard to manage if the number of <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> instances becomes

  1055. effectively unbounded.</p>

  1056. <section id="using-loggeradapters-to-impart-contextual-information">

  1057. <h3>Using LoggerAdapters to impart contextual information<a class="headerlink" href="#using-loggeradapters-to-impart-contextual-information" title="Link to this heading">¶</a></h3>

  1058. <p>An easy way in which you can pass contextual information to be output along

  1059. with logging event information is to use the <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> class.

  1060. This class is designed to look like a <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a>, so that you can call

  1061. <a class="reference internal" href="../library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="../library/logging.html#logging.info" title="logging.info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code></a>, <a class="reference internal" href="../library/logging.html#logging.warning" title="logging.warning"><code class="xref py py-meth docutils literal notranslate"><span class="pre">warning()</span></code></a>, <a class="reference internal" href="../library/logging.html#logging.error" title="logging.error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code></a>,

  1062. <a class="reference internal" href="../library/logging.html#logging.exception" title="logging.exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exception()</span></code></a>, <a class="reference internal" href="../library/logging.html#logging.critical" title="logging.critical"><code class="xref py py-meth docutils literal notranslate"><span class="pre">critical()</span></code></a> and <a class="reference internal" href="../library/logging.html#logging.log" title="logging.log"><code class="xref py py-meth docutils literal notranslate"><span class="pre">log()</span></code></a>. These methods have the

  1063. same signatures as their counterparts in <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a>, so you can use the

  1064. two types of instances interchangeably.</p>

  1065. <p>When you create an instance of <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a>, you pass it a

  1066. <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> instance and a dict-like object which contains your contextual

  1067. information. When you call one of the logging methods on an instance of

  1068. <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a>, it delegates the call to the underlying instance of

  1069. <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> passed to its constructor, and arranges to pass the contextual

  1070. information in the delegated call. Here’s a snippet from the code of

  1071. <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a>:</p>

  1072. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">debug</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1073. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1074. <span class="sd">    Delegate a debug call to the underlying logger, after adding</span>

  1075. <span class="sd">    contextual information from this adapter instance.</span>

  1076. <span class="sd">    &quot;&quot;&quot;</span>

  1077.     <span class="n">msg</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">process</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">)</span>

  1078.     <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1079. </pre></div>

  1080. </div>

  1081. <p>The <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter.process" title="logging.LoggerAdapter.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">process()</span></code></a> method of <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> is where the

  1082. contextual information is added to the logging output. It’s passed the message

  1083. and keyword arguments of the logging call, and it passes back (potentially)

  1084. modified versions of these to use in the call to the underlying logger. The

  1085. default implementation of this method leaves the message alone, but inserts

  1086. an ‘extra’ key in the keyword argument whose value is the dict-like object

  1087. passed to the constructor. Of course, if you had passed an ‘extra’ keyword

  1088. argument in the call to the adapter, it will be silently overwritten.</p>

  1089. <p>The advantage of using ‘extra’ is that the values in the dict-like object are

  1090. merged into the <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> instance’s __dict__, allowing you to use

  1091. customized strings with your <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> instances which know about

  1092. the keys of the dict-like object. If you need a different method, e.g. if you

  1093. want to prepend or append the contextual information to the message string,

  1094. you just need to subclass <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> and override

  1095. <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter.process" title="logging.LoggerAdapter.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">process()</span></code></a> to do what you need. Here is a simple example:</p>

  1096. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CustomAdapter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">LoggerAdapter</span><span class="p">):</span>

  1097. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1098. <span class="sd">    This example adapter expects the passed in dict-like object to have a</span>

  1099. <span class="sd">    &#39;connid&#39; key, whose value in brackets is prepended to the log message.</span>

  1100. <span class="sd">    &quot;&quot;&quot;</span>

  1101.     <span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">):</span>

  1102.         <span class="k">return</span> <span class="s1">&#39;[</span><span class="si">%s</span><span class="s1">] </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">extra</span><span class="p">[</span><span class="s1">&#39;connid&#39;</span><span class="p">],</span> <span class="n">msg</span><span class="p">),</span> <span class="n">kwargs</span>

  1103. </pre></div>

  1104. </div>

  1105. <p>which you can use like this:</p>

  1106. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  1107. <span class="n">adapter</span> <span class="o">=</span> <span class="n">CustomAdapter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;connid&#39;</span><span class="p">:</span> <span class="n">some_conn_id</span><span class="p">})</span>

  1108. </pre></div>

  1109. </div>

  1110. <p>Then any events that you log to the adapter will have the value of

  1111. <code class="docutils literal notranslate"><span class="pre">some_conn_id</span></code> prepended to the log messages.</p>

  1112. <section id="using-objects-other-than-dicts-to-pass-contextual-information">

  1113. <h4>Using objects other than dicts to pass contextual information<a class="headerlink" href="#using-objects-other-than-dicts-to-pass-contextual-information" title="Link to this heading">¶</a></h4>

  1114. <p>You don’t need to pass an actual dict to a <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> - you could

  1115. pass an instance of a class which implements <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code> and <code class="docutils literal notranslate"><span class="pre">__iter__</span></code> so

  1116. that it looks like a dict to logging. This would be useful if you want to

  1117. generate values dynamically (whereas the values in a dict would be constant).</p>

  1118. </section>

  1119. </section>

  1120. <section id="using-filters-to-impart-contextual-information">

  1121. <span id="filters-contextual"></span><h3>Using Filters to impart contextual information<a class="headerlink" href="#using-filters-to-impart-contextual-information" title="Link to this heading">¶</a></h3>

  1122. <p>You can also add contextual information to log output using a user-defined

  1123. <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a>. <code class="docutils literal notranslate"><span class="pre">Filter</span></code> instances are allowed to modify the <code class="docutils literal notranslate"><span class="pre">LogRecords</span></code>

  1124. passed to them, including adding additional attributes which can then be output

  1125. using a suitable format string, or if needed a custom <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a>.</p>

  1126. <p>For example in a web application, the request being processed (or at least,

  1127. the interesting parts of it) can be stored in a threadlocal

  1128. (<a class="reference internal" href="../library/threading.html#threading.local" title="threading.local"><code class="xref py py-class docutils literal notranslate"><span class="pre">threading.local</span></code></a>) variable, and then accessed from a <code class="docutils literal notranslate"><span class="pre">Filter</span></code> to

  1129. add, say, information from the request - say, the remote IP address and remote

  1130. user’s username - to the <code class="docutils literal notranslate"><span class="pre">LogRecord</span></code>, using the attribute names ‘ip’ and

  1131. ‘user’ as in the <code class="docutils literal notranslate"><span class="pre">LoggerAdapter</span></code> example above. In that case, the same format

  1132. string can be used to get similar output to that shown above. Here’s an example

  1133. script:</p>

  1134. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  1135. <span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">choice</span>

  1136. 

  1137. <span class="k">class</span> <span class="nc">ContextFilter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Filter</span><span class="p">):</span>

  1138. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1139. <span class="sd">    This is a filter which injects contextual information into the log.</span>

  1140. 

  1141. <span class="sd">    Rather than use actual contextual information, we just use random</span>

  1142. <span class="sd">    data in this demo.</span>

  1143. <span class="sd">    &quot;&quot;&quot;</span>

  1144. 

  1145.     <span class="n">USERS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;jim&#39;</span><span class="p">,</span> <span class="s1">&#39;fred&#39;</span><span class="p">,</span> <span class="s1">&#39;sheila&#39;</span><span class="p">]</span>

  1146.     <span class="n">IPS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;123.231.231.123&#39;</span><span class="p">,</span> <span class="s1">&#39;127.0.0.1&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.0.1&#39;</span><span class="p">]</span>

  1147. 

  1148.     <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  1149. 

  1150.         <span class="n">record</span><span class="o">.</span><span class="n">ip</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">ContextFilter</span><span class="o">.</span><span class="n">IPS</span><span class="p">)</span>

  1151.         <span class="n">record</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">ContextFilter</span><span class="o">.</span><span class="n">USERS</span><span class="p">)</span>

  1152.         <span class="k">return</span> <span class="kc">True</span>

  1153. 

  1154. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1155.     <span class="n">levels</span> <span class="o">=</span> <span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">)</span>

  1156.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span>

  1157.                         <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(asctime)-15s</span><span class="s1"> </span><span class="si">%(name)-5s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> IP: </span><span class="si">%(ip)-15s</span><span class="s1"> User: </span><span class="si">%(user)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  1158.     <span class="n">a1</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;a.b.c&#39;</span><span class="p">)</span>

  1159.     <span class="n">a2</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;d.e.f&#39;</span><span class="p">)</span>

  1160. 

  1161.     <span class="n">f</span> <span class="o">=</span> <span class="n">ContextFilter</span><span class="p">()</span>

  1162.     <span class="n">a1</span><span class="o">.</span><span class="n">addFilter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  1163.     <span class="n">a2</span><span class="o">.</span><span class="n">addFilter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  1164.     <span class="n">a1</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;A debug message&#39;</span><span class="p">)</span>

  1165.     <span class="n">a1</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;An info message with </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;some parameters&#39;</span><span class="p">)</span>

  1166.     <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>

  1167.         <span class="n">lvl</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">levels</span><span class="p">)</span>

  1168.         <span class="n">lvlname</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLevelName</span><span class="p">(</span><span class="n">lvl</span><span class="p">)</span>

  1169.         <span class="n">a2</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">lvl</span><span class="p">,</span> <span class="s1">&#39;A message at </span><span class="si">%s</span><span class="s1"> level with </span><span class="si">%d</span><span class="s1"> </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">lvlname</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;parameters&#39;</span><span class="p">)</span>

  1170. </pre></div>

  1171. </div>

  1172. <p>which, when run, produces something like:</p>

  1173. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message

  1174. 2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters

  1175. 2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters

  1176. 2010-09-06 22:38:15,300 d.e.f ERROR    IP: 127.0.0.1       User: jim      A message at ERROR level with 2 parameters

  1177. 2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 127.0.0.1       User: sheila   A message at DEBUG level with 2 parameters

  1178. 2010-09-06 22:38:15,300 d.e.f ERROR    IP: 123.231.231.123 User: fred     A message at ERROR level with 2 parameters

  1179. 2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters

  1180. 2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters

  1181. 2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 192.168.0.1     User: jim      A message at DEBUG level with 2 parameters

  1182. 2010-09-06 22:38:15,301 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters

  1183. 2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters

  1184. 2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters

  1185. </pre></div>

  1186. </div>

  1187. </section>

  1188. </section>

  1189. <section id="use-of-contextvars">

  1190. <h2>Use of <code class="docutils literal notranslate"><span class="pre">contextvars</span></code><a class="headerlink" href="#use-of-contextvars" title="Link to this heading">¶</a></h2>

  1191. <p>Since Python 3.7, the <a class="reference internal" href="../library/contextvars.html#module-contextvars" title="contextvars: Context Variables"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></code></a> module has provided context-local storage

  1192. which works for both <a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> and <a class="reference internal" href="../library/asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> processing needs. This type

  1193. of storage may thus be generally preferable to thread-locals. The following example

  1194. shows how, in a multi-threaded environment, logs can populated with contextual

  1195. information such as, for example, request attributes handled by web applications.</p>

  1196. <p>For the purposes of illustration, say that you have different web applications, each

  1197. independent of the other but running in the same Python process and using a library

  1198. common to them. How can each of these applications have their own log, where all

  1199. logging messages from the library (and other request processing code) are directed to

  1200. the appropriate application’s log file, while including in the log additional

  1201. contextual information such as client IP, HTTP request method and client username?</p>

  1202. <p>Let’s assume that the library can be simulated by the following code:</p>

  1203. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># webapplib.py</span>

  1204. <span class="kn">import</span> <span class="nn">logging</span>

  1205. <span class="kn">import</span> <span class="nn">time</span>

  1206. 

  1207. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  1208. 

  1209. <span class="k">def</span> <span class="nf">useful</span><span class="p">():</span>

  1210.     <span class="c1"># Just a representative event logged from the library</span>

  1211.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Hello from webapplib!&#39;</span><span class="p">)</span>

  1212.     <span class="c1"># Just sleep for a bit so other threads get to run</span>

  1213.     <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.01</span><span class="p">)</span>

  1214. </pre></div>

  1215. </div>

  1216. <p>We can simulate the multiple web applications by means of two simple classes,

  1217. <code class="docutils literal notranslate"><span class="pre">Request</span></code> and <code class="docutils literal notranslate"><span class="pre">WebApp</span></code>. These simulate how real threaded web applications work -

  1218. each request is handled by a thread:</p>

  1219. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># main.py</span>

  1220. <span class="kn">import</span> <span class="nn">argparse</span>

  1221. <span class="kn">from</span> <span class="nn">contextvars</span> <span class="kn">import</span> <span class="n">ContextVar</span>

  1222. <span class="kn">import</span> <span class="nn">logging</span>

  1223. <span class="kn">import</span> <span class="nn">os</span>

  1224. <span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">choice</span>

  1225. <span class="kn">import</span> <span class="nn">threading</span>

  1226. <span class="kn">import</span> <span class="nn">webapplib</span>

  1227. 

  1228. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  1229. <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1230. <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1231. 

  1232. <span class="k">class</span> <span class="nc">Request</span><span class="p">:</span>

  1233. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1234. <span class="sd">    A simple dummy request class which just holds dummy HTTP request method,</span>

  1235. <span class="sd">    client IP address and client username</span>

  1236. <span class="sd">    &quot;&quot;&quot;</span>

  1237.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">method</span><span class="p">,</span> <span class="n">ip</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>

  1238.         <span class="bp">self</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="n">method</span>

  1239.         <span class="bp">self</span><span class="o">.</span><span class="n">ip</span> <span class="o">=</span> <span class="n">ip</span>

  1240.         <span class="bp">self</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">user</span>

  1241. 

  1242. <span class="c1"># A dummy set of requests which will be used in the simulation - we&#39;ll just pick</span>

  1243. <span class="c1"># from this list randomly. Note that all GET requests are from 192.168.2.XXX</span>

  1244. <span class="c1"># addresses, whereas POST requests are from 192.16.3.XXX addresses. Three users</span>

  1245. <span class="c1"># are represented in the sample requests.</span>

  1246. 

  1247. <span class="n">REQUESTS</span> <span class="o">=</span> <span class="p">[</span>

  1248.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.2.20&#39;</span><span class="p">,</span> <span class="s1">&#39;jim&#39;</span><span class="p">),</span>

  1249.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;POST&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.3.20&#39;</span><span class="p">,</span> <span class="s1">&#39;fred&#39;</span><span class="p">),</span>

  1250.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.2.21&#39;</span><span class="p">,</span> <span class="s1">&#39;sheila&#39;</span><span class="p">),</span>

  1251.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;POST&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.3.21&#39;</span><span class="p">,</span> <span class="s1">&#39;jim&#39;</span><span class="p">),</span>

  1252.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.2.22&#39;</span><span class="p">,</span> <span class="s1">&#39;fred&#39;</span><span class="p">),</span>

  1253.     <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;POST&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.3.22&#39;</span><span class="p">,</span> <span class="s1">&#39;sheila&#39;</span><span class="p">),</span>

  1254. <span class="p">]</span>

  1255. 

  1256. <span class="c1"># Note that the format string includes references to request context information</span>

  1257. <span class="c1"># such as HTTP method, client IP and username</span>

  1258. 

  1259. <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(threadName)-11s</span><span class="s1"> </span><span class="si">%(appName)s</span><span class="s1"> </span><span class="si">%(name)-9s</span><span class="s1"> </span><span class="si">%(user)-6s</span><span class="s1"> </span><span class="si">%(ip)s</span><span class="s1"> </span><span class="si">%(method)-4s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  1260. 

  1261. <span class="c1"># Create our context variables. These will be filled at the start of request</span>

  1262. <span class="c1"># processing, and used in the logging that happens during that processing</span>

  1263. 

  1264. <span class="n">ctx_request</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">&#39;request&#39;</span><span class="p">)</span>

  1265. <span class="n">ctx_appname</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">&#39;appname&#39;</span><span class="p">)</span>

  1266. 

  1267. <span class="k">class</span> <span class="nc">InjectingFilter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Filter</span><span class="p">):</span>

  1268. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1269. <span class="sd">    A filter which injects context-specific information into logs and ensures</span>

  1270. <span class="sd">    that only information for a specific webapp is included in its log</span>

  1271. <span class="sd">    &quot;&quot;&quot;</span>

  1272.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">app</span><span class="p">):</span>

  1273.         <span class="bp">self</span><span class="o">.</span><span class="n">app</span> <span class="o">=</span> <span class="n">app</span>

  1274. 

  1275.     <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  1276.         <span class="n">request</span> <span class="o">=</span> <span class="n">ctx_request</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>

  1277.         <span class="n">record</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">method</span>

  1278.         <span class="n">record</span><span class="o">.</span><span class="n">ip</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">ip</span>

  1279.         <span class="n">record</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">user</span>

  1280.         <span class="n">record</span><span class="o">.</span><span class="n">appName</span> <span class="o">=</span> <span class="n">appName</span> <span class="o">=</span> <span class="n">ctx_appname</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>

  1281.         <span class="k">return</span> <span class="n">appName</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">app</span><span class="o">.</span><span class="n">name</span>

  1282. 

  1283. <span class="k">class</span> <span class="nc">WebApp</span><span class="p">:</span>

  1284. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1285. <span class="sd">    A dummy web application class which has its own handler and filter for a</span>

  1286. <span class="sd">    webapp-specific log.</span>

  1287. <span class="sd">    &quot;&quot;&quot;</span>

  1288.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  1289.         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>

  1290.         <span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="n">name</span> <span class="o">+</span> <span class="s1">&#39;.log&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span>

  1291.         <span class="n">f</span> <span class="o">=</span> <span class="n">InjectingFilter</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

  1292.         <span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  1293.         <span class="n">handler</span><span class="o">.</span><span class="n">addFilter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  1294.         <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  1295.         <span class="bp">self</span><span class="o">.</span><span class="n">num_requests</span> <span class="o">=</span> <span class="mi">0</span>

  1296. 

  1297.     <span class="k">def</span> <span class="nf">process_request</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>

  1298. <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>

  1299. <span class="sd">        This is the dummy method for processing a request. It&#39;s called on a</span>

  1300. <span class="sd">        different thread for every request. We store the context information into</span>

  1301. <span class="sd">        the context vars before doing anything else.</span>

  1302. <span class="sd">        &quot;&quot;&quot;</span>

  1303.         <span class="n">ctx_request</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>

  1304.         <span class="n">ctx_appname</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  1305.         <span class="bp">self</span><span class="o">.</span><span class="n">num_requests</span> <span class="o">+=</span> <span class="mi">1</span>

  1306.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Request processing started&#39;</span><span class="p">)</span>

  1307.         <span class="n">webapplib</span><span class="o">.</span><span class="n">useful</span><span class="p">()</span>

  1308.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Request processing finished&#39;</span><span class="p">)</span>

  1309. 

  1310. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  1311.     <span class="n">fn</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="vm">__file__</span><span class="p">))[</span><span class="mi">0</span><span class="p">]</span>

  1312.     <span class="n">adhf</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentDefaultsHelpFormatter</span>

  1313.     <span class="n">ap</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">formatter_class</span><span class="o">=</span><span class="n">adhf</span><span class="p">,</span> <span class="n">prog</span><span class="o">=</span><span class="n">fn</span><span class="p">,</span>

  1314.                                  <span class="n">description</span><span class="o">=</span><span class="s1">&#39;Simulate a couple of web &#39;</span>

  1315.                                              <span class="s1">&#39;applications handling some &#39;</span>

  1316.                                              <span class="s1">&#39;requests, showing how request &#39;</span>

  1317.                                              <span class="s1">&#39;context can be used to &#39;</span>

  1318.                                              <span class="s1">&#39;populate logs&#39;</span><span class="p">)</span>

  1319.     <span class="n">aa</span> <span class="o">=</span> <span class="n">ap</span><span class="o">.</span><span class="n">add_argument</span>

  1320.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;--count&#39;</span><span class="p">,</span> <span class="s1">&#39;-c&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;How many requests to simulate&#39;</span><span class="p">)</span>

  1321.     <span class="n">options</span> <span class="o">=</span> <span class="n">ap</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>

  1322. 

  1323.     <span class="c1"># Create the dummy webapps and put them in a list which we can use to select</span>

  1324.     <span class="c1"># from randomly</span>

  1325.     <span class="n">app1</span> <span class="o">=</span> <span class="n">WebApp</span><span class="p">(</span><span class="s1">&#39;app1&#39;</span><span class="p">)</span>

  1326.     <span class="n">app2</span> <span class="o">=</span> <span class="n">WebApp</span><span class="p">(</span><span class="s1">&#39;app2&#39;</span><span class="p">)</span>

  1327.     <span class="n">apps</span> <span class="o">=</span> <span class="p">[</span><span class="n">app1</span><span class="p">,</span> <span class="n">app2</span><span class="p">]</span>

  1328.     <span class="n">threads</span> <span class="o">=</span> <span class="p">[]</span>

  1329.     <span class="c1"># Add a common handler which will capture all events</span>

  1330.     <span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="s1">&#39;app.log&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span>

  1331.     <span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  1332.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  1333. 

  1334.     <span class="c1"># Generate calls to process requests</span>

  1335.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">count</span><span class="p">):</span>

  1336.         <span class="k">try</span><span class="p">:</span>

  1337.             <span class="c1"># Pick an app at random and a request for it to process</span>

  1338.             <span class="n">app</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">apps</span><span class="p">)</span>

  1339.             <span class="n">request</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">REQUESTS</span><span class="p">)</span>

  1340.             <span class="c1"># Process the request in its own thread</span>

  1341.             <span class="n">t</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">app</span><span class="o">.</span><span class="n">process_request</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">request</span><span class="p">,))</span>

  1342.             <span class="n">threads</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">t</span><span class="p">)</span>

  1343.             <span class="n">t</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1344.         <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>

  1345.             <span class="k">break</span>

  1346. 

  1347.     <span class="c1"># Wait for the threads to terminate</span>

  1348.     <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">threads</span><span class="p">:</span>

  1349.         <span class="n">t</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1350. 

  1351.     <span class="k">for</span> <span class="n">app</span> <span class="ow">in</span> <span class="n">apps</span><span class="p">:</span>

  1352.         <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%s</span><span class="s1"> processed </span><span class="si">%s</span><span class="s1"> requests&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">app</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">app</span><span class="o">.</span><span class="n">num_requests</span><span class="p">))</span>

  1353. 

  1354. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1355.     <span class="n">main</span><span class="p">()</span>

  1356. </pre></div>

  1357. </div>

  1358. <p>If you run the above, you should find that roughly half the requests go

  1359. into <code class="file docutils literal notranslate"><span class="pre">app1.log</span></code> and the rest into <code class="file docutils literal notranslate"><span class="pre">app2.log</span></code>, and the all the requests are

  1360. logged to <code class="file docutils literal notranslate"><span class="pre">app.log</span></code>. Each webapp-specific log will contain only log entries for

  1361. only that webapp, and the request information will be displayed consistently in the

  1362. log (i.e. the information in each dummy request will always appear together in a log

  1363. line). This is illustrated by the following shell output:</p>

  1364. <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>~/logging-contextual-webapp$<span class="w"> </span>python<span class="w"> </span>main.py

  1365. app1<span class="w"> </span>processed<span class="w"> </span><span class="m">51</span><span class="w"> </span>requests

  1366. app2<span class="w"> </span>processed<span class="w"> </span><span class="m">49</span><span class="w"> </span>requests

  1367. ~/logging-contextual-webapp$<span class="w"> </span>wc<span class="w"> </span>-l<span class="w"> </span>*.log

  1368. <span class="w">  </span><span class="m">153</span><span class="w"> </span>app1.log

  1369. <span class="w">  </span><span class="m">147</span><span class="w"> </span>app2.log

  1370. <span class="w">  </span><span class="m">300</span><span class="w"> </span>app.log

  1371. <span class="w">  </span><span class="m">600</span><span class="w"> </span>total

  1372. ~/logging-contextual-webapp$<span class="w"> </span>head<span class="w"> </span>-3<span class="w"> </span>app1.log

  1373. Thread-3<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1374. Thread-3<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>webapplib<span class="w"> </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1375. Thread-5<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1376. ~/logging-contextual-webapp$<span class="w"> </span>head<span class="w"> </span>-3<span class="w"> </span>app2.log

  1377. Thread-1<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>__main__<span class="w">  </span>sheila<span class="w"> </span><span class="m">192</span>.168.2.21<span class="w"> </span>GET<span class="w">  </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1378. Thread-1<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>webapplib<span class="w"> </span>sheila<span class="w"> </span><span class="m">192</span>.168.2.21<span class="w"> </span>GET<span class="w">  </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1379. Thread-2<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.2.20<span class="w"> </span>GET<span class="w">  </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1380. ~/logging-contextual-webapp$<span class="w"> </span>head<span class="w"> </span>app.log

  1381. Thread-1<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>__main__<span class="w">  </span>sheila<span class="w"> </span><span class="m">192</span>.168.2.21<span class="w"> </span>GET<span class="w">  </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1382. Thread-1<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>webapplib<span class="w"> </span>sheila<span class="w"> </span><span class="m">192</span>.168.2.21<span class="w"> </span>GET<span class="w">  </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1383. Thread-2<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.2.20<span class="w"> </span>GET<span class="w">  </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1384. Thread-3<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1385. Thread-2<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>webapplib<span class="w"> </span>jim<span class="w">    </span><span class="m">192</span>.168.2.20<span class="w"> </span>GET<span class="w">  </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1386. Thread-3<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>webapplib<span class="w"> </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1387. Thread-4<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>__main__<span class="w">  </span>fred<span class="w">   </span><span class="m">192</span>.168.2.22<span class="w"> </span>GET<span class="w">  </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1388. Thread-5<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1389. Thread-4<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app2<span class="w"> </span>webapplib<span class="w"> </span>fred<span class="w">   </span><span class="m">192</span>.168.2.22<span class="w"> </span>GET<span class="w">  </span>Hello<span class="w"> </span>from<span class="w"> </span>webapplib!

  1390. Thread-6<span class="w"> </span><span class="o">(</span>process_request<span class="o">)</span><span class="w"> </span>app1<span class="w"> </span>__main__<span class="w">  </span>jim<span class="w">    </span><span class="m">192</span>.168.3.21<span class="w"> </span>POST<span class="w"> </span>Request<span class="w"> </span>processing<span class="w"> </span>started

  1391. ~/logging-contextual-webapp$<span class="w"> </span>grep<span class="w"> </span>app1<span class="w"> </span>app1.log<span class="w"> </span><span class="p">|</span><span class="w"> </span>wc<span class="w"> </span>-l

  1392. <span class="m">153</span>

  1393. ~/logging-contextual-webapp$<span class="w"> </span>grep<span class="w"> </span>app2<span class="w"> </span>app2.log<span class="w"> </span><span class="p">|</span><span class="w"> </span>wc<span class="w"> </span>-l

  1394. <span class="m">147</span>

  1395. ~/logging-contextual-webapp$<span class="w"> </span>grep<span class="w"> </span>app1<span class="w"> </span>app.log<span class="w"> </span><span class="p">|</span><span class="w"> </span>wc<span class="w"> </span>-l

  1396. <span class="m">153</span>

  1397. ~/logging-contextual-webapp$<span class="w"> </span>grep<span class="w"> </span>app2<span class="w"> </span>app.log<span class="w"> </span><span class="p">|</span><span class="w"> </span>wc<span class="w"> </span>-l

  1398. <span class="m">147</span>

  1399. </pre></div>

  1400. </div>

  1401. </section>

  1402. <section id="imparting-contextual-information-in-handlers">

  1403. <h2>Imparting contextual information in handlers<a class="headerlink" href="#imparting-contextual-information-in-handlers" title="Link to this heading">¶</a></h2>

  1404. <p>Each <a class="reference internal" href="../library/logging.html#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> has its own chain of filters.

  1405. If you want to add contextual information to a <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> without leaking

  1406. it to other handlers, you can use a filter that returns

  1407. a new <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> instead of modifying it in-place, as shown in the following script:</p>

  1408. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">copy</span>

  1409. <span class="kn">import</span> <span class="nn">logging</span>

  1410. 

  1411. <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">record</span><span class="p">:</span> <span class="n">logging</span><span class="o">.</span><span class="n">LogRecord</span><span class="p">):</span>

  1412.     <span class="n">record</span> <span class="o">=</span> <span class="n">copy</span><span class="o">.</span><span class="n">copy</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  1413.     <span class="n">record</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="s1">&#39;jim&#39;</span>

  1414.     <span class="k">return</span> <span class="n">record</span>

  1415. 

  1416. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1417.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1418.     <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  1419.     <span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  1420.     <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(message)s</span><span class="s1"> from </span><span class="si">%(user)-8s</span><span class="s1">&#39;</span><span class="p">)</span>

  1421.     <span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  1422.     <span class="n">handler</span><span class="o">.</span><span class="n">addFilter</span><span class="p">(</span><span class="nb">filter</span><span class="p">)</span>

  1423.     <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  1424. 

  1425.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;A log message&#39;</span><span class="p">)</span>

  1426. </pre></div>

  1427. </div>

  1428. </section>

  1429. <section id="logging-to-a-single-file-from-multiple-processes">

  1430. <span id="multiple-processes"></span><h2>Logging to a single file from multiple processes<a class="headerlink" href="#logging-to-a-single-file-from-multiple-processes" title="Link to this heading">¶</a></h2>

  1431. <p>Although logging is thread-safe, and logging to a single file from multiple

  1432. threads in a single process <em>is</em> supported, logging to a single file from

  1433. <em>multiple processes</em> is <em>not</em> supported, because there is no standard way to

  1434. serialize access to a single file across multiple processes in Python. If you

  1435. need to log to a single file from multiple processes, one way of doing this is

  1436. to have all the processes log to a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler" title="logging.handlers.SocketHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SocketHandler</span></code></a>, and have a

  1437. separate process which implements a socket server which reads from the socket

  1438. and logs to file. (If you prefer, you can dedicate one thread in one of the

  1439. existing processes to perform this function.)

  1440. <a class="reference internal" href="#network-logging"><span class="std std-ref">This section</span></a> documents this approach in more detail and

  1441. includes a working socket receiver which can be used as a starting point for you

  1442. to adapt in your own applications.</p>

  1443. <p>You could also write your own handler which uses the <a class="reference internal" href="../library/multiprocessing.html#multiprocessing.Lock" title="multiprocessing.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a>

  1444. class from the <a class="reference internal" href="../library/multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module to serialize access to the

  1445. file from your processes. The existing <a class="reference internal" href="../library/logging.handlers.html#logging.FileHandler" title="logging.FileHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileHandler</span></code></a> and subclasses do

  1446. not make use of <a class="reference internal" href="../library/multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> at present, though they may do so in the

  1447. future. Note that at present, the <a class="reference internal" href="../library/multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module does not provide

  1448. working lock functionality on all platforms (see

  1449. <a class="reference external" href="https://bugs.python.org/issue3770">https://bugs.python.org/issue3770</a>).</p>

  1450. <p>Alternatively, you can use a <code class="docutils literal notranslate"><span class="pre">Queue</span></code> and a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueHandler" title="logging.handlers.QueueHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueHandler</span></code></a> to send

  1451. all logging events to one of the processes in your multi-process application.

  1452. The following example script demonstrates how you can do this; in the example

  1453. a separate listener process listens for events sent by other processes and logs

  1454. them according to its own logging configuration. Although the example only

  1455. demonstrates one way of doing it (for example, you may want to use a listener

  1456. thread rather than a separate listener process – the implementation would be

  1457. analogous) it does allow for completely different logging configurations for

  1458. the listener and the other processes in your application, and can be used as

  1459. the basis for code meeting your own specific requirements:</p>

  1460. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># You&#39;ll need these imports in your own code</span>

  1461. <span class="kn">import</span> <span class="nn">logging</span>

  1462. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  1463. <span class="kn">import</span> <span class="nn">multiprocessing</span>

  1464. 

  1465. <span class="c1"># Next two import lines for this demo only</span>

  1466. <span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">choice</span><span class="p">,</span> <span class="n">random</span>

  1467. <span class="kn">import</span> <span class="nn">time</span>

  1468. 

  1469. <span class="c1">#</span>

  1470. <span class="c1"># Because you&#39;ll want to define the logging configurations for listener and workers, the</span>

  1471. <span class="c1"># listener and worker process functions take a configurer parameter which is a callable</span>

  1472. <span class="c1"># for configuring logging for that process. These functions are also passed the queue,</span>

  1473. <span class="c1"># which they use for communication.</span>

  1474. <span class="c1">#</span>

  1475. <span class="c1"># In practice, you can configure the listener however you want, but note that in this</span>

  1476. <span class="c1"># simple example, the listener does not apply level or filter logic to received records.</span>

  1477. <span class="c1"># In practice, you would probably want to do this logic in the worker processes, to avoid</span>

  1478. <span class="c1"># sending events which would be filtered out between processes.</span>

  1479. <span class="c1">#</span>

  1480. <span class="c1"># The size of the rotated files is made small so you can see the results easily.</span>

  1481. <span class="k">def</span> <span class="nf">listener_configurer</span><span class="p">():</span>

  1482.     <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1483.     <span class="n">h</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">RotatingFileHandler</span><span class="p">(</span><span class="s1">&#39;mptest.log&#39;</span><span class="p">,</span> <span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="mi">300</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>

  1484.     <span class="n">f</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(processName)-10s</span><span class="s1"> </span><span class="si">%(name)s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  1485.     <span class="n">h</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  1486.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  1487. 

  1488. <span class="c1"># This is the listener process top-level loop: wait for logging events</span>

  1489. <span class="c1"># (LogRecords)on the queue and handle them, quit when you get a None for a</span>

  1490. <span class="c1"># LogRecord.</span>

  1491. <span class="k">def</span> <span class="nf">listener_process</span><span class="p">(</span><span class="n">queue</span><span class="p">,</span> <span class="n">configurer</span><span class="p">):</span>

  1492.     <span class="n">configurer</span><span class="p">()</span>

  1493.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  1494.         <span class="k">try</span><span class="p">:</span>

  1495.             <span class="n">record</span> <span class="o">=</span> <span class="n">queue</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>

  1496.             <span class="k">if</span> <span class="n">record</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>  <span class="c1"># We send this as a sentinel to tell the listener to quit.</span>

  1497.                 <span class="k">break</span>

  1498.             <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  1499.             <span class="n">logger</span><span class="o">.</span><span class="n">handle</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>  <span class="c1"># No level or filter logic applied - just do it!</span>

  1500.         <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>

  1501.             <span class="kn">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">traceback</span>

  1502.             <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Whoops! Problem:&#39;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>

  1503.             <span class="n">traceback</span><span class="o">.</span><span class="n">print_exc</span><span class="p">(</span><span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>

  1504. 

  1505. <span class="c1"># Arrays used for random selections in this demo</span>

  1506. 

  1507. <span class="n">LEVELS</span> <span class="o">=</span> <span class="p">[</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span>

  1508.           <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">]</span>

  1509. 

  1510. <span class="n">LOGGERS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;a.b.c&#39;</span><span class="p">,</span> <span class="s1">&#39;d.e.f&#39;</span><span class="p">]</span>

  1511. 

  1512. <span class="n">MESSAGES</span> <span class="o">=</span> <span class="p">[</span>

  1513.     <span class="s1">&#39;Random message #1&#39;</span><span class="p">,</span>

  1514.     <span class="s1">&#39;Random message #2&#39;</span><span class="p">,</span>

  1515.     <span class="s1">&#39;Random message #3&#39;</span><span class="p">,</span>

  1516. <span class="p">]</span>

  1517. 

  1518. <span class="c1"># The worker configuration is done at the start of the worker process run.</span>

  1519. <span class="c1"># Note that on Windows you can&#39;t rely on fork semantics, so each process</span>

  1520. <span class="c1"># will run the logging configuration code when it starts.</span>

  1521. <span class="k">def</span> <span class="nf">worker_configurer</span><span class="p">(</span><span class="n">queue</span><span class="p">):</span>

  1522.     <span class="n">h</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">QueueHandler</span><span class="p">(</span><span class="n">queue</span><span class="p">)</span>  <span class="c1"># Just the one handler needed</span>

  1523.     <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1524.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  1525.     <span class="c1"># send all messages, for demo; no other level or filter logic applied.</span>

  1526.     <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1527. 

  1528. <span class="c1"># This is the worker process top-level loop, which just logs ten events with</span>

  1529. <span class="c1"># random intervening delays before terminating.</span>

  1530. <span class="c1"># The print messages are just so you know it&#39;s doing something!</span>

  1531. <span class="k">def</span> <span class="nf">worker_process</span><span class="p">(</span><span class="n">queue</span><span class="p">,</span> <span class="n">configurer</span><span class="p">):</span>

  1532.     <span class="n">configurer</span><span class="p">(</span><span class="n">queue</span><span class="p">)</span>

  1533.     <span class="n">name</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">current_process</span><span class="p">()</span><span class="o">.</span><span class="n">name</span>

  1534.     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Worker started: </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span>

  1535.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>

  1536.         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">random</span><span class="p">())</span>

  1537.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">choice</span><span class="p">(</span><span class="n">LOGGERS</span><span class="p">))</span>

  1538.         <span class="n">level</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">LEVELS</span><span class="p">)</span>

  1539.         <span class="n">message</span> <span class="o">=</span> <span class="n">choice</span><span class="p">(</span><span class="n">MESSAGES</span><span class="p">)</span>

  1540.         <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>

  1541.     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Worker finished: </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span>

  1542. 

  1543. <span class="c1"># Here&#39;s where the demo gets orchestrated. Create the queue, create and start</span>

  1544. <span class="c1"># the listener, create ten workers and start them, wait for them to finish,</span>

  1545. <span class="c1"># then send a None to the queue to tell the listener to finish.</span>

  1546. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  1547.     <span class="n">queue</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Queue</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>

  1548.     <span class="n">listener</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">listener_process</span><span class="p">,</span>

  1549.                                        <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">queue</span><span class="p">,</span> <span class="n">listener_configurer</span><span class="p">))</span>

  1550.     <span class="n">listener</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1551.     <span class="n">workers</span> <span class="o">=</span> <span class="p">[]</span>

  1552.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>

  1553.         <span class="n">worker</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">worker_process</span><span class="p">,</span>

  1554.                                          <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">queue</span><span class="p">,</span> <span class="n">worker_configurer</span><span class="p">))</span>

  1555.         <span class="n">workers</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">worker</span><span class="p">)</span>

  1556.         <span class="n">worker</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1557.     <span class="k">for</span> <span class="n">w</span> <span class="ow">in</span> <span class="n">workers</span><span class="p">:</span>

  1558.         <span class="n">w</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1559.     <span class="n">queue</span><span class="o">.</span><span class="n">put_nowait</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span>

  1560.     <span class="n">listener</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1561. 

  1562. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1563.     <span class="n">main</span><span class="p">()</span>

  1564. </pre></div>

  1565. </div>

  1566. <p>A variant of the above script keeps the logging in the main process, in a

  1567. separate thread:</p>

  1568. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  1569. <span class="kn">import</span> <span class="nn">logging.config</span>

  1570. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  1571. <span class="kn">from</span> <span class="nn">multiprocessing</span> <span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Queue</span>

  1572. <span class="kn">import</span> <span class="nn">random</span>

  1573. <span class="kn">import</span> <span class="nn">threading</span>

  1574. <span class="kn">import</span> <span class="nn">time</span>

  1575. 

  1576. <span class="k">def</span> <span class="nf">logger_thread</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>

  1577.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  1578.         <span class="n">record</span> <span class="o">=</span> <span class="n">q</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>

  1579.         <span class="k">if</span> <span class="n">record</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1580.             <span class="k">break</span>

  1581.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  1582.         <span class="n">logger</span><span class="o">.</span><span class="n">handle</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  1583. 

  1584. 

  1585. <span class="k">def</span> <span class="nf">worker_process</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>

  1586.     <span class="n">qh</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">QueueHandler</span><span class="p">(</span><span class="n">q</span><span class="p">)</span>

  1587.     <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1588.     <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1589.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">qh</span><span class="p">)</span>

  1590.     <span class="n">levels</span> <span class="o">=</span> <span class="p">[</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span>

  1591.               <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">]</span>

  1592.     <span class="n">loggers</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;foo.bar&#39;</span><span class="p">,</span> <span class="s1">&#39;foo.bar.baz&#39;</span><span class="p">,</span>

  1593.                <span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;spam.ham&#39;</span><span class="p">,</span> <span class="s1">&#39;spam.ham.eggs&#39;</span><span class="p">]</span>

  1594.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">100</span><span class="p">):</span>

  1595.         <span class="n">lvl</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">levels</span><span class="p">)</span>

  1596.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">loggers</span><span class="p">))</span>

  1597.         <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">lvl</span><span class="p">,</span> <span class="s1">&#39;Message no. </span><span class="si">%d</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>

  1598. 

  1599. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1600.     <span class="n">q</span> <span class="o">=</span> <span class="n">Queue</span><span class="p">()</span>

  1601.     <span class="n">d</span> <span class="o">=</span> <span class="p">{</span>

  1602.         <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  1603.         <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  1604.             <span class="s1">&#39;detailed&#39;</span><span class="p">:</span> <span class="p">{</span>

  1605.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.Formatter&#39;</span><span class="p">,</span>

  1606.                 <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(name)-15s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(processName)-10s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  1607.             <span class="p">}</span>

  1608.         <span class="p">},</span>

  1609.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  1610.             <span class="s1">&#39;console&#39;</span><span class="p">:</span> <span class="p">{</span>

  1611.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  1612.                 <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;INFO&#39;</span><span class="p">,</span>

  1613.             <span class="p">},</span>

  1614.             <span class="s1">&#39;file&#39;</span><span class="p">:</span> <span class="p">{</span>

  1615.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  1616.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog.log&#39;</span><span class="p">,</span>

  1617.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  1618.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span><span class="p">,</span>

  1619.             <span class="p">},</span>

  1620.             <span class="s1">&#39;foofile&#39;</span><span class="p">:</span> <span class="p">{</span>

  1621.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  1622.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog-foo.log&#39;</span><span class="p">,</span>

  1623.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  1624.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span><span class="p">,</span>

  1625.             <span class="p">},</span>

  1626.             <span class="s1">&#39;errors&#39;</span><span class="p">:</span> <span class="p">{</span>

  1627.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  1628.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog-errors.log&#39;</span><span class="p">,</span>

  1629.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  1630.                 <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;ERROR&#39;</span><span class="p">,</span>

  1631.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span><span class="p">,</span>

  1632.             <span class="p">},</span>

  1633.         <span class="p">},</span>

  1634.         <span class="s1">&#39;loggers&#39;</span><span class="p">:</span> <span class="p">{</span>

  1635.             <span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="p">{</span>

  1636.                 <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;foofile&#39;</span><span class="p">]</span>

  1637.             <span class="p">}</span>

  1638.         <span class="p">},</span>

  1639.         <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  1640.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  1641.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">,</span> <span class="s1">&#39;file&#39;</span><span class="p">,</span> <span class="s1">&#39;errors&#39;</span><span class="p">]</span>

  1642.         <span class="p">},</span>

  1643.     <span class="p">}</span>

  1644.     <span class="n">workers</span> <span class="o">=</span> <span class="p">[]</span>

  1645.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">):</span>

  1646.         <span class="n">wp</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">worker_process</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">&#39;worker </span><span class="si">%d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">),</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,))</span>

  1647.         <span class="n">workers</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">wp</span><span class="p">)</span>

  1648.         <span class="n">wp</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1649.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>

  1650.     <span class="n">lp</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">logger_thread</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,))</span>

  1651.     <span class="n">lp</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1652.     <span class="c1"># At this point, the main process could do some useful work of its own</span>

  1653.     <span class="c1"># Once it&#39;s done that, it can wait for the workers to terminate...</span>

  1654.     <span class="k">for</span> <span class="n">wp</span> <span class="ow">in</span> <span class="n">workers</span><span class="p">:</span>

  1655.         <span class="n">wp</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1656.     <span class="c1"># And now tell the logging thread to finish up, too</span>

  1657.     <span class="n">q</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span>

  1658.     <span class="n">lp</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1659. </pre></div>

  1660. </div>

  1661. <p>This variant shows how you can e.g. apply configuration for particular loggers

  1662. - e.g. the <code class="docutils literal notranslate"><span class="pre">foo</span></code> logger has a special handler which stores all events in the

  1663. <code class="docutils literal notranslate"><span class="pre">foo</span></code> subsystem in a file <code class="docutils literal notranslate"><span class="pre">mplog-foo.log</span></code>. This will be used by the logging

  1664. machinery in the main process (even though the logging events are generated in

  1665. the worker processes) to direct the messages to the appropriate destinations.</p>

  1666. <section id="using-concurrent-futures-processpoolexecutor">

  1667. <h3>Using concurrent.futures.ProcessPoolExecutor<a class="headerlink" href="#using-concurrent-futures-processpoolexecutor" title="Link to this heading">¶</a></h3>

  1668. <p>If you want to use <a class="reference internal" href="../library/concurrent.futures.html#concurrent.futures.ProcessPoolExecutor" title="concurrent.futures.ProcessPoolExecutor"><code class="xref py py-class docutils literal notranslate"><span class="pre">concurrent.futures.ProcessPoolExecutor</span></code></a> to start

  1669. your worker processes, you need to create the queue slightly differently.

  1670. Instead of</p>

  1671. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">queue</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Queue</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>

  1672. </pre></div>

  1673. </div>

  1674. <p>you should use</p>

  1675. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">queue</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Manager</span><span class="p">()</span><span class="o">.</span><span class="n">Queue</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>  <span class="c1"># also works with the examples above</span>

  1676. </pre></div>

  1677. </div>

  1678. <p>and you can then replace the worker creation from this:</p>

  1679. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">workers</span> <span class="o">=</span> <span class="p">[]</span>

  1680. <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>

  1681.     <span class="n">worker</span> <span class="o">=</span> <span class="n">multiprocessing</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">worker_process</span><span class="p">,</span>

  1682.                                      <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">queue</span><span class="p">,</span> <span class="n">worker_configurer</span><span class="p">))</span>

  1683.     <span class="n">workers</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">worker</span><span class="p">)</span>

  1684.     <span class="n">worker</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  1685. <span class="k">for</span> <span class="n">w</span> <span class="ow">in</span> <span class="n">workers</span><span class="p">:</span>

  1686.     <span class="n">w</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  1687. </pre></div>

  1688. </div>

  1689. <p>to this (remembering to first import <a class="reference internal" href="../library/concurrent.futures.html#module-concurrent.futures" title="concurrent.futures: Execute computations concurrently using threads or processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.futures</span></code></a>):</p>

  1690. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">concurrent</span><span class="o">.</span><span class="n">futures</span><span class="o">.</span><span class="n">ProcessPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>

  1691.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>

  1692.         <span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">worker_process</span><span class="p">,</span> <span class="n">queue</span><span class="p">,</span> <span class="n">worker_configurer</span><span class="p">)</span>

  1693. </pre></div>

  1694. </div>

  1695. </section>

  1696. <section id="deploying-web-applications-using-gunicorn-and-uwsgi">

  1697. <h3>Deploying Web applications using Gunicorn and uWSGI<a class="headerlink" href="#deploying-web-applications-using-gunicorn-and-uwsgi" title="Link to this heading">¶</a></h3>

  1698. <p>When deploying Web applications using <a class="reference external" href="https://gunicorn.org/">Gunicorn</a> or <a class="reference external" href="https://uwsgi-docs.readthedocs.io/en/latest/">uWSGI</a> (or similar), multiple worker

  1699. processes are created to handle client requests. In such environments, avoid creating

  1700. file-based handlers directly in your web application. Instead, use a

  1701. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler" title="logging.handlers.SocketHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SocketHandler</span></code></a> to log from the web application to a listener in a separate

  1702. process. This can be set up using a process management tool such as Supervisor - see

  1703. <a class="reference internal" href="#running-a-logging-socket-listener-in-production">Running a logging socket listener in production</a> for more details.</p>

  1704. </section>

  1705. </section>

  1706. <section id="using-file-rotation">

  1707. <h2>Using file rotation<a class="headerlink" href="#using-file-rotation" title="Link to this heading">¶</a></h2>

  1708. <p>Sometimes you want to let a log file grow to a certain size, then open a new

  1709. file and log to that. You may want to keep a certain number of these files, and

  1710. when that many files have been created, rotate the files so that the number of

  1711. files and the size of the files both remain bounded. For this usage pattern, the

  1712. logging package provides a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.RotatingFileHandler" title="logging.handlers.RotatingFileHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">RotatingFileHandler</span></code></a>:</p>

  1713. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">glob</span>

  1714. <span class="kn">import</span> <span class="nn">logging</span>

  1715. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  1716. 

  1717. <span class="n">LOG_FILENAME</span> <span class="o">=</span> <span class="s1">&#39;logging_rotatingfile_example.out&#39;</span>

  1718. 

  1719. <span class="c1"># Set up a specific logger with our desired output level</span>

  1720. <span class="n">my_logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;MyLogger&#39;</span><span class="p">)</span>

  1721. <span class="n">my_logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1722. 

  1723. <span class="c1"># Add the log message handler to the logger</span>

  1724. <span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">RotatingFileHandler</span><span class="p">(</span>

  1725.               <span class="n">LOG_FILENAME</span><span class="p">,</span> <span class="n">maxBytes</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">backupCount</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>

  1726. 

  1727. <span class="n">my_logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  1728. 

  1729. <span class="c1"># Log some messages</span>

  1730. <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">):</span>

  1731.     <span class="n">my_logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;i = </span><span class="si">%d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">i</span><span class="p">)</span>

  1732. 

  1733. <span class="c1"># See what files are created</span>

  1734. <span class="n">logfiles</span> <span class="o">=</span> <span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%s</span><span class="s1">*&#39;</span> <span class="o">%</span> <span class="n">LOG_FILENAME</span><span class="p">)</span>

  1735. 

  1736. <span class="k">for</span> <span class="n">filename</span> <span class="ow">in</span> <span class="n">logfiles</span><span class="p">:</span>

  1737.     <span class="nb">print</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>

  1738. </pre></div>

  1739. </div>

  1740. <p>The result should be 6 separate files, each with part of the log history for the

  1741. application:</p>

  1742. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>logging_rotatingfile_example.out

  1743. logging_rotatingfile_example.out.1

  1744. logging_rotatingfile_example.out.2

  1745. logging_rotatingfile_example.out.3

  1746. logging_rotatingfile_example.out.4

  1747. logging_rotatingfile_example.out.5

  1748. </pre></div>

  1749. </div>

  1750. <p>The most current file is always <code class="file docutils literal notranslate"><span class="pre">logging_rotatingfile_example.out</span></code>,

  1751. and each time it reaches the size limit it is renamed with the suffix

  1752. <code class="docutils literal notranslate"><span class="pre">.1</span></code>. Each of the existing backup files is renamed to increment the suffix

  1753. (<code class="docutils literal notranslate"><span class="pre">.1</span></code> becomes <code class="docutils literal notranslate"><span class="pre">.2</span></code>, etc.)  and the <code class="docutils literal notranslate"><span class="pre">.6</span></code> file is erased.</p>

  1754. <p>Obviously this example sets the log length much too small as an extreme

  1755. example.  You would want to set <em>maxBytes</em> to an appropriate value.</p>

  1756. </section>

  1757. <section id="use-of-alternative-formatting-styles">

  1758. <span id="format-styles"></span><h2>Use of alternative formatting styles<a class="headerlink" href="#use-of-alternative-formatting-styles" title="Link to this heading">¶</a></h2>

  1759. <p>When logging was added to the Python standard library, the only way of

  1760. formatting messages with variable content was to use the %-formatting

  1761. method. Since then, Python has gained two new formatting approaches:

  1762. <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a> (added in Python 2.4) and <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a>

  1763. (added in Python 2.6).</p>

  1764. <p>Logging (as of 3.2) provides improved support for these two additional

  1765. formatting styles. The <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> class been enhanced to take an

  1766. additional, optional keyword parameter named <code class="docutils literal notranslate"><span class="pre">style</span></code>. This defaults to

  1767. <code class="docutils literal notranslate"><span class="pre">'%'</span></code>, but other possible values are <code class="docutils literal notranslate"><span class="pre">'{'</span></code> and <code class="docutils literal notranslate"><span class="pre">'$'</span></code>, which correspond

  1768. to the other two formatting styles. Backwards compatibility is maintained by

  1769. default (as you would expect), but by explicitly specifying a style parameter,

  1770. you get the ability to specify format strings which work with

  1771. <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> or <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>. Here’s an example console

  1772. session to show the possibilities:</p>

  1773. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">logging</span>

  1774. <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  1775. <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1776. <span class="gp">&gt;&gt;&gt; </span><span class="n">handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  1777. <span class="gp">&gt;&gt;&gt; </span><span class="n">bf</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">{asctime}</span><span class="s1"> </span><span class="si">{name}</span><span class="s1"> </span><span class="si">{levelname:8s}</span><span class="s1"> </span><span class="si">{message}</span><span class="s1">&#39;</span><span class="p">,</span>

  1778. <span class="gp">... </span>                       <span class="n">style</span><span class="o">=</span><span class="s1">&#39;{&#39;</span><span class="p">)</span>

  1779. <span class="gp">&gt;&gt;&gt; </span><span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">bf</span><span class="p">)</span>

  1780. <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  1781. <span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;foo.bar&#39;</span><span class="p">)</span>

  1782. <span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;This is a DEBUG message&#39;</span><span class="p">)</span>

  1783. <span class="go">2010-10-28 15:11:55,341 foo.bar DEBUG    This is a DEBUG message</span>

  1784. <span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;This is a CRITICAL message&#39;</span><span class="p">)</span>

  1785. <span class="go">2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message</span>

  1786. <span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;$asctime $name $</span><span class="si">{levelname}</span><span class="s1"> $message&#39;</span><span class="p">,</span>

  1787. <span class="gp">... </span>                       <span class="n">style</span><span class="o">=</span><span class="s1">&#39;$&#39;</span><span class="p">)</span>

  1788. <span class="gp">&gt;&gt;&gt; </span><span class="n">handler</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">df</span><span class="p">)</span>

  1789. <span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;This is a DEBUG message&#39;</span><span class="p">)</span>

  1790. <span class="go">2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message</span>

  1791. <span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;This is a CRITICAL message&#39;</span><span class="p">)</span>

  1792. <span class="go">2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message</span>

  1793. <span class="gp">&gt;&gt;&gt;</span>

  1794. </pre></div>

  1795. </div>

  1796. <p>Note that the formatting of logging messages for final output to logs is

  1797. completely independent of how an individual logging message is constructed.

  1798. That can still use %-formatting, as shown here:</p>

  1799. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;This is an</span><span class="si">%s</span><span class="s1"> </span><span class="si">%s</span><span class="s1"> </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;other,&#39;</span><span class="p">,</span> <span class="s1">&#39;ERROR,&#39;</span><span class="p">,</span> <span class="s1">&#39;message&#39;</span><span class="p">)</span>

  1800. <span class="go">2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message</span>

  1801. <span class="gp">&gt;&gt;&gt;</span>

  1802. </pre></div>

  1803. </div>

  1804. <p>Logging calls (<code class="docutils literal notranslate"><span class="pre">logger.debug()</span></code>, <code class="docutils literal notranslate"><span class="pre">logger.info()</span></code> etc.) only take

  1805. positional parameters for the actual logging message itself, with keyword

  1806. parameters used only for determining options for how to handle the actual

  1807. logging call (e.g. the <code class="docutils literal notranslate"><span class="pre">exc_info</span></code> keyword parameter to indicate that

  1808. traceback information should be logged, or the <code class="docutils literal notranslate"><span class="pre">extra</span></code> keyword parameter

  1809. to indicate additional contextual information to be added to the log). So

  1810. you cannot directly make logging calls using <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> or

  1811. <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a> syntax, because internally the logging package

  1812. uses %-formatting to merge the format string and the variable arguments.

  1813. There would be no changing this while preserving backward compatibility, since

  1814. all logging calls which are out there in existing code will be using %-format

  1815. strings.</p>

  1816. <p>There is, however, a way that you can use {}- and $- formatting to construct

  1817. your individual log messages. Recall that for a message you can use an

  1818. arbitrary object as a message format string, and that the logging package will

  1819. call <code class="docutils literal notranslate"><span class="pre">str()</span></code> on that object to get the actual format string. Consider the

  1820. following two classes:</p>

  1821. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BraceMessage</span><span class="p">:</span>

  1822.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1823.         <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span>

  1824.         <span class="bp">self</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="n">args</span>

  1825.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  1826. 

  1827.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1828.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="o">*</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span>

  1829. 

  1830. <span class="k">class</span> <span class="nc">DollarMessage</span><span class="p">:</span>

  1831.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1832.         <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span>

  1833.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  1834. 

  1835.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1836.         <span class="kn">from</span> <span class="nn">string</span> <span class="kn">import</span> <span class="n">Template</span>

  1837.         <span class="k">return</span> <span class="n">Template</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fmt</span><span class="p">)</span><span class="o">.</span><span class="n">substitute</span><span class="p">(</span><span class="o">**</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span>

  1838. </pre></div>

  1839. </div>

  1840. <p>Either of these can be used in place of a format string, to allow {}- or

  1841. $-formatting to be used to build the actual “message” part which appears in the

  1842. formatted log output in place of “%(message)s” or “{message}” or “$message”.

  1843. It’s a little unwieldy to use the class names whenever you want to log

  1844. something, but it’s quite palatable if you use an alias such as __ (double

  1845. underscore — not to be confused with _, the single underscore used as a

  1846. synonym/alias for <a class="reference internal" href="../library/gettext.html#gettext.gettext" title="gettext.gettext"><code class="xref py py-func docutils literal notranslate"><span class="pre">gettext.gettext()</span></code></a> or its brethren).</p>

  1847. <p>The above classes are not included in Python, though they’re easy enough to

  1848. copy and paste into your own code. They can be used as follows (assuming that

  1849. they’re declared in a module called <code class="docutils literal notranslate"><span class="pre">wherever</span></code>):</p>

  1850. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">wherever</span> <span class="kn">import</span> <span class="n">BraceMessage</span> <span class="k">as</span> <span class="n">__</span>

  1851. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with </span><span class="si">{0}</span><span class="s1"> </span><span class="si">{name}</span><span class="s1">&#39;</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">&#39;placeholders&#39;</span><span class="p">))</span>

  1852. <span class="go">Message with 2 placeholders</span>

  1853. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Point</span><span class="p">:</span> <span class="k">pass</span>

  1854. <span class="gp">...</span>

  1855. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Point</span><span class="p">()</span>

  1856. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mf">0.5</span>

  1857. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="mf">0.5</span>

  1858. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with coordinates: (</span><span class="si">{point.x:.2f}</span><span class="s1">, </span><span class="si">{point.y:.2f}</span><span class="s1">)&#39;</span><span class="p">,</span>

  1859. <span class="gp">... </span>      <span class="n">point</span><span class="o">=</span><span class="n">p</span><span class="p">))</span>

  1860. <span class="go">Message with coordinates: (0.50, 0.50)</span>

  1861. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">wherever</span> <span class="kn">import</span> <span class="n">DollarMessage</span> <span class="k">as</span> <span class="n">__</span>

  1862. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with $num $what&#39;</span><span class="p">,</span> <span class="n">num</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">what</span><span class="o">=</span><span class="s1">&#39;placeholders&#39;</span><span class="p">))</span>

  1863. <span class="go">Message with 2 placeholders</span>

  1864. <span class="gp">&gt;&gt;&gt;</span>

  1865. </pre></div>

  1866. </div>

  1867. <p>While the above examples use <code class="docutils literal notranslate"><span class="pre">print()</span></code> to show how the formatting works, you

  1868. would of course use <code class="docutils literal notranslate"><span class="pre">logger.debug()</span></code> or similar to actually log using this

  1869. approach.</p>

  1870. <p>One thing to note is that you pay no significant performance penalty with this

  1871. approach: the actual formatting happens not when you make the logging call, but

  1872. when (and if) the logged message is actually about to be output to a log by a

  1873. handler. So the only slightly unusual thing which might trip you up is that the

  1874. parentheses go around the format string and the arguments, not just the format

  1875. string. That’s because the __ notation is just syntax sugar for a constructor

  1876. call to one of the <code class="samp docutils literal notranslate"><em><span class="pre">XXX</span></em><span class="pre">Message</span></code> classes.</p>

  1877. <p>If you prefer, you can use a <a class="reference internal" href="../library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> to achieve a similar effect

  1878. to the above, as in the following example:</p>

  1879. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  1880. 

  1881. <span class="k">class</span> <span class="nc">Message</span><span class="p">:</span>

  1882.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>

  1883.         <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span>

  1884.         <span class="bp">self</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="n">args</span>

  1885. 

  1886.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1887.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="o">*</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">)</span>

  1888. 

  1889. <span class="k">class</span> <span class="nc">StyleAdapter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">LoggerAdapter</span><span class="p">):</span>

  1890.     <span class="k">def</span> <span class="nf">log</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">msg</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">stacklevel</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1891.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">isEnabledFor</span><span class="p">(</span><span class="n">level</span><span class="p">):</span>

  1892.             <span class="n">msg</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">process</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">)</span>

  1893.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="n">Message</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="n">args</span><span class="p">),</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">,</span>

  1894.                             <span class="n">stacklevel</span><span class="o">=</span><span class="n">stacklevel</span><span class="o">+</span><span class="mi">1</span><span class="p">)</span>

  1895. 

  1896. <span class="n">logger</span> <span class="o">=</span> <span class="n">StyleAdapter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">))</span>

  1897. 

  1898. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  1899.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Hello, </span><span class="si">{}</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;world!&#39;</span><span class="p">)</span>

  1900. 

  1901. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1902.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  1903.     <span class="n">main</span><span class="p">()</span>

  1904. </pre></div>

  1905. </div>

  1906. <p>The above script should log the message <code class="docutils literal notranslate"><span class="pre">Hello,</span> <span class="pre">world!</span></code> when run with

  1907. Python 3.8 or later.</p>

  1908. </section>

  1909. <section id="customizing-logrecord">

  1910. <span id="custom-logrecord"></span><h2>Customizing <code class="docutils literal notranslate"><span class="pre">LogRecord</span></code><a class="headerlink" href="#customizing-logrecord" title="Link to this heading">¶</a></h2>

  1911. <p>Every logging event is represented by a <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> instance.

  1912. When an event is logged and not filtered out by a logger’s level, a

  1913. <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> is created, populated with information about the event and

  1914. then passed to the handlers for that logger (and its ancestors, up to and

  1915. including the logger where further propagation up the hierarchy is disabled).

  1916. Before Python 3.2, there were only two places where this creation was done:</p>

  1917. <ul class="simple">

  1918. <li><p><a class="reference internal" href="../library/logging.html#logging.Logger.makeRecord" title="logging.Logger.makeRecord"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Logger.makeRecord()</span></code></a>, which is called in the normal process of

  1919. logging an event. This invoked <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> directly to create an

  1920. instance.</p></li>

  1921. <li><p><a class="reference internal" href="../library/logging.html#logging.makeLogRecord" title="logging.makeLogRecord"><code class="xref py py-func docutils literal notranslate"><span class="pre">makeLogRecord()</span></code></a>, which is called with a dictionary containing

  1922. attributes to be added to the LogRecord. This is typically invoked when a

  1923. suitable dictionary has been received over the network (e.g. in pickle form

  1924. via a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SocketHandler" title="logging.handlers.SocketHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SocketHandler</span></code></a>, or in JSON form via an

  1925. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.HTTPHandler" title="logging.handlers.HTTPHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">HTTPHandler</span></code></a>).</p></li>

  1926. </ul>

  1927. <p>This has usually meant that if you need to do anything special with a

  1928. <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>, you’ve had to do one of the following.</p>

  1929. <ul class="simple">

  1930. <li><p>Create your own <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> subclass, which overrides

  1931. <a class="reference internal" href="../library/logging.html#logging.Logger.makeRecord" title="logging.Logger.makeRecord"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Logger.makeRecord()</span></code></a>, and set it using <a class="reference internal" href="../library/logging.html#logging.setLoggerClass" title="logging.setLoggerClass"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLoggerClass()</span></code></a>

  1932. before any loggers that you care about are instantiated.</p></li>

  1933. <li><p>Add a <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> to a logger or handler, which does the

  1934. necessary special manipulation you need when its

  1935. <a class="reference internal" href="../library/logging.html#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> method is called.</p></li>

  1936. </ul>

  1937. <p>The first approach would be a little unwieldy in the scenario where (say)

  1938. several different libraries wanted to do different things. Each would attempt

  1939. to set its own <a class="reference internal" href="../library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> subclass, and the one which did this last would

  1940. win.</p>

  1941. <p>The second approach works reasonably well for many cases, but does not allow

  1942. you to e.g. use a specialized subclass of <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>. Library

  1943. developers can set a suitable filter on their loggers, but they would have to

  1944. remember to do this every time they introduced a new logger (which they would

  1945. do simply by adding new packages or modules and doing</p>

  1946. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  1947. </pre></div>

  1948. </div>

  1949. <p>at module level). It’s probably one too many things to think about. Developers

  1950. could also add the filter to a <a class="reference internal" href="../library/logging.handlers.html#logging.NullHandler" title="logging.NullHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullHandler</span></code></a> attached to their

  1951. top-level logger, but this would not be invoked if an application developer

  1952. attached a handler to a lower-level library logger — so output from that

  1953. handler would not reflect the intentions of the library developer.</p>

  1954. <p>In Python 3.2 and later, <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> creation is done through a

  1955. factory, which you can specify. The factory is just a callable you can set with

  1956. <a class="reference internal" href="../library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a>, and interrogate with

  1957. <a class="reference internal" href="../library/logging.html#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogRecordFactory()</span></code></a>. The factory is invoked with the same

  1958. signature as the <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> constructor, as <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>

  1959. is the default setting for the factory.</p>

  1960. <p>This approach allows a custom factory to control all aspects of LogRecord

  1961. creation. For example, you could return a subclass, or just add some additional

  1962. attributes to the record once created, using a pattern similar to this:</p>

  1963. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">old_factory</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogRecordFactory</span><span class="p">()</span>

  1964. 

  1965. <span class="k">def</span> <span class="nf">record_factory</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1966.     <span class="n">record</span> <span class="o">=</span> <span class="n">old_factory</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1967.     <span class="n">record</span><span class="o">.</span><span class="n">custom_attribute</span> <span class="o">=</span> <span class="mh">0xdecafbad</span>

  1968.     <span class="k">return</span> <span class="n">record</span>

  1969. 

  1970. <span class="n">logging</span><span class="o">.</span><span class="n">setLogRecordFactory</span><span class="p">(</span><span class="n">record_factory</span><span class="p">)</span>

  1971. </pre></div>

  1972. </div>

  1973. <p>This pattern allows different libraries to chain factories together, and as

  1974. long as they don’t overwrite each other’s attributes or unintentionally

  1975. overwrite the attributes provided as standard, there should be no surprises.

  1976. However, it should be borne in mind that each link in the chain adds run-time

  1977. overhead to all logging operations, and the technique should only be used when

  1978. the use of a <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> does not provide the desired result.</p>

  1979. </section>

  1980. <section id="subclassing-queuehandler-and-queuelistener-a-zeromq-example">

  1981. <span id="zeromq-handlers"></span><h2>Subclassing QueueHandler and QueueListener- a ZeroMQ example<a class="headerlink" href="#subclassing-queuehandler-and-queuelistener-a-zeromq-example" title="Link to this heading">¶</a></h2>

  1982. <section id="subclass-queuehandler">

  1983. <h3>Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code><a class="headerlink" href="#subclass-queuehandler" title="Link to this heading">¶</a></h3>

  1984. <p>You can use a <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueHandler" title="logging.handlers.QueueHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueHandler</span></code></a> subclass to send messages to other kinds

  1985. of queues, for example a ZeroMQ ‘publish’ socket. In the example below,the

  1986. socket is created separately and passed to the handler (as its ‘queue’):</p>

  1987. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">zmq</span>   <span class="c1"># using pyzmq, the Python binding for ZeroMQ</span>

  1988. <span class="kn">import</span> <span class="nn">json</span>  <span class="c1"># for serializing records portably</span>

  1989. 

  1990. <span class="n">ctx</span> <span class="o">=</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Context</span><span class="p">()</span>

  1991. <span class="n">sock</span> <span class="o">=</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Socket</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="n">zmq</span><span class="o">.</span><span class="n">PUB</span><span class="p">)</span>  <span class="c1"># or zmq.PUSH, or other suitable value</span>

  1992. <span class="n">sock</span><span class="o">.</span><span class="n">bind</span><span class="p">(</span><span class="s1">&#39;tcp://*:5556&#39;</span><span class="p">)</span>        <span class="c1"># or wherever</span>

  1993. 

  1994. <span class="k">class</span> <span class="nc">ZeroMQSocketHandler</span><span class="p">(</span><span class="n">QueueHandler</span><span class="p">):</span>

  1995.     <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  1996.         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">send_json</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>

  1997. 

  1998. 

  1999. <span class="n">handler</span> <span class="o">=</span> <span class="n">ZeroMQSocketHandler</span><span class="p">(</span><span class="n">sock</span><span class="p">)</span>

  2000. </pre></div>

  2001. </div>

  2002. <p>Of course there are other ways of organizing this, for example passing in the

  2003. data needed by the handler to create the socket:</p>

  2004. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ZeroMQSocketHandler</span><span class="p">(</span><span class="n">QueueHandler</span><span class="p">):</span>

  2005.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uri</span><span class="p">,</span> <span class="n">socktype</span><span class="o">=</span><span class="n">zmq</span><span class="o">.</span><span class="n">PUB</span><span class="p">,</span> <span class="n">ctx</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  2006.         <span class="bp">self</span><span class="o">.</span><span class="n">ctx</span> <span class="o">=</span> <span class="n">ctx</span> <span class="ow">or</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Context</span><span class="p">()</span>

  2007.         <span class="n">socket</span> <span class="o">=</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Socket</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">ctx</span><span class="p">,</span> <span class="n">socktype</span><span class="p">)</span>

  2008.         <span class="n">socket</span><span class="o">.</span><span class="n">bind</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>

  2009.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">socket</span><span class="p">)</span>

  2010. 

  2011.     <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  2012.         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">send_json</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>

  2013. 

  2014.     <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2015.         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  2016. </pre></div>

  2017. </div>

  2018. </section>

  2019. <section id="subclass-queuelistener">

  2020. <h3>Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code><a class="headerlink" href="#subclass-queuelistener" title="Link to this heading">¶</a></h3>

  2021. <p>You can also subclass <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.QueueListener" title="logging.handlers.QueueListener"><code class="xref py py-class docutils literal notranslate"><span class="pre">QueueListener</span></code></a> to get messages from other kinds

  2022. of queues, for example a ZeroMQ ‘subscribe’ socket. Here’s an example:</p>

  2023. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ZeroMQSocketListener</span><span class="p">(</span><span class="n">QueueListener</span><span class="p">):</span>

  2024.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uri</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">handlers</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2025.         <span class="bp">self</span><span class="o">.</span><span class="n">ctx</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;ctx&#39;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Context</span><span class="p">()</span>

  2026.         <span class="n">socket</span> <span class="o">=</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Socket</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">ctx</span><span class="p">,</span> <span class="n">zmq</span><span class="o">.</span><span class="n">SUB</span><span class="p">)</span>

  2027.         <span class="n">socket</span><span class="o">.</span><span class="n">setsockopt_string</span><span class="p">(</span><span class="n">zmq</span><span class="o">.</span><span class="n">SUBSCRIBE</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>  <span class="c1"># subscribe to everything</span>

  2028.         <span class="n">socket</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">uri</span><span class="p">)</span>

  2029.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">socket</span><span class="p">,</span> <span class="o">*</span><span class="n">handlers</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  2030. 

  2031.     <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2032.         <span class="n">msg</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">recv_json</span><span class="p">()</span>

  2033.         <span class="k">return</span> <span class="n">logging</span><span class="o">.</span><span class="n">makeLogRecord</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>

  2034. </pre></div>

  2035. </div>

  2036. </section>

  2037. </section>

  2038. <section id="subclassing-queuehandler-and-queuelistener-a-pynng-example">

  2039. <span id="pynng-handlers"></span><h2>Subclassing QueueHandler and QueueListener- a <code class="docutils literal notranslate"><span class="pre">pynng</span></code> example<a class="headerlink" href="#subclassing-queuehandler-and-queuelistener-a-pynng-example" title="Link to this heading">¶</a></h2>

  2040. <p>In a similar way to the above section, we can implement a listener and handler

  2041. using <a class="reference external" href="https://pypi.org/project/pynng/">pynng</a>, which is a Python binding to

  2042. <a class="reference external" href="https://nng.nanomsg.org/">NNG</a>, billed as a spiritual successor to ZeroMQ.

  2043. The following snippets illustrate – you can test them in an environment which has

  2044. <code class="docutils literal notranslate"><span class="pre">pynng</span></code> installed. Just for variety, we present the listener first.</p>

  2045. <section id="id3">

  2046. <h3>Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code><a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>

  2047. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># listener.py</span>

  2048. <span class="kn">import</span> <span class="nn">json</span>

  2049. <span class="kn">import</span> <span class="nn">logging</span>

  2050. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  2051. 

  2052. <span class="kn">import</span> <span class="nn">pynng</span>

  2053. 

  2054. <span class="n">DEFAULT_ADDR</span> <span class="o">=</span> <span class="s2">&quot;tcp://localhost:13232&quot;</span>

  2055. 

  2056. <span class="n">interrupted</span> <span class="o">=</span> <span class="kc">False</span>

  2057. 

  2058. <span class="k">class</span> <span class="nc">NNGSocketListener</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">QueueListener</span><span class="p">):</span>

  2059. 

  2060.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uri</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">handlers</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2061.         <span class="c1"># Have a timeout for interruptability, and open a</span>

  2062.         <span class="c1"># subscriber socket</span>

  2063.         <span class="n">socket</span> <span class="o">=</span> <span class="n">pynng</span><span class="o">.</span><span class="n">Sub0</span><span class="p">(</span><span class="n">listen</span><span class="o">=</span><span class="n">uri</span><span class="p">,</span> <span class="n">recv_timeout</span><span class="o">=</span><span class="mi">500</span><span class="p">)</span>

  2064.         <span class="c1"># The b&#39;&#39; subscription matches all topics</span>

  2065.         <span class="n">topics</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s1">&#39;topics&#39;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span> <span class="ow">or</span> <span class="sa">b</span><span class="s1">&#39;&#39;</span>

  2066.         <span class="n">socket</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="n">topics</span><span class="p">)</span>

  2067.         <span class="c1"># We treat the socket as a queue</span>

  2068.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">socket</span><span class="p">,</span> <span class="o">*</span><span class="n">handlers</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  2069. 

  2070.     <span class="k">def</span> <span class="nf">dequeue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">block</span><span class="p">):</span>

  2071.         <span class="n">data</span> <span class="o">=</span> <span class="kc">None</span>

  2072.         <span class="c1"># Keep looping while not interrupted and no data received over the</span>

  2073.         <span class="c1"># socket</span>

  2074.         <span class="k">while</span> <span class="ow">not</span> <span class="n">interrupted</span><span class="p">:</span>

  2075.             <span class="k">try</span><span class="p">:</span>

  2076.                 <span class="n">data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="n">block</span><span class="o">=</span><span class="n">block</span><span class="p">)</span>

  2077.                 <span class="k">break</span>

  2078.             <span class="k">except</span> <span class="n">pynng</span><span class="o">.</span><span class="n">Timeout</span><span class="p">:</span>

  2079.                 <span class="k">pass</span>

  2080.             <span class="k">except</span> <span class="n">pynng</span><span class="o">.</span><span class="n">Closed</span><span class="p">:</span>  <span class="c1"># sometimes happens when you hit Ctrl-C</span>

  2081.                 <span class="k">break</span>

  2082.         <span class="k">if</span> <span class="n">data</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  2083.             <span class="k">return</span> <span class="kc">None</span>

  2084.         <span class="c1"># Get the logging event sent from a publisher</span>

  2085.         <span class="n">event</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">&#39;utf-8&#39;</span><span class="p">))</span>

  2086.         <span class="k">return</span> <span class="n">logging</span><span class="o">.</span><span class="n">makeLogRecord</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>

  2087. 

  2088.     <span class="k">def</span> <span class="nf">enqueue_sentinel</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2089.         <span class="c1"># Not used in this implementation, as the socket isn&#39;t really a</span>

  2090.         <span class="c1"># queue</span>

  2091.         <span class="k">pass</span>

  2092. 

  2093. <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;pynng&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">propagate</span> <span class="o">=</span> <span class="kc">False</span>

  2094. <span class="n">listener</span> <span class="o">=</span> <span class="n">NNGSocketListener</span><span class="p">(</span><span class="n">DEFAULT_ADDR</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">(),</span> <span class="n">topics</span><span class="o">=</span><span class="sa">b</span><span class="s1">&#39;&#39;</span><span class="p">)</span>

  2095. <span class="n">listener</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2096. <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Press Ctrl-C to stop.&#39;</span><span class="p">)</span>

  2097. <span class="k">try</span><span class="p">:</span>

  2098.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  2099.         <span class="k">pass</span>

  2100. <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>

  2101.     <span class="n">interrupted</span> <span class="o">=</span> <span class="kc">True</span>

  2102. <span class="k">finally</span><span class="p">:</span>

  2103.     <span class="n">listener</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>

  2104. </pre></div>

  2105. </div>

  2106. </section>

  2107. <section id="id4">

  2108. <h3>Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code><a class="headerlink" href="#id4" title="Link to this heading">¶</a></h3>

  2109. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># sender.py</span>

  2110. <span class="kn">import</span> <span class="nn">json</span>

  2111. <span class="kn">import</span> <span class="nn">logging</span>

  2112. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  2113. <span class="kn">import</span> <span class="nn">time</span>

  2114. <span class="kn">import</span> <span class="nn">random</span>

  2115. 

  2116. <span class="kn">import</span> <span class="nn">pynng</span>

  2117. 

  2118. <span class="n">DEFAULT_ADDR</span> <span class="o">=</span> <span class="s2">&quot;tcp://localhost:13232&quot;</span>

  2119. 

  2120. <span class="k">class</span> <span class="nc">NNGSocketHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">QueueHandler</span><span class="p">):</span>

  2121. 

  2122.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uri</span><span class="p">):</span>

  2123.         <span class="n">socket</span> <span class="o">=</span> <span class="n">pynng</span><span class="o">.</span><span class="n">Pub0</span><span class="p">(</span><span class="n">dial</span><span class="o">=</span><span class="n">uri</span><span class="p">,</span> <span class="n">send_timeout</span><span class="o">=</span><span class="mi">500</span><span class="p">)</span>

  2124.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">socket</span><span class="p">)</span>

  2125. 

  2126.     <span class="k">def</span> <span class="nf">enqueue</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  2127.         <span class="c1"># Send the record as UTF-8 encoded JSON</span>

  2128.         <span class="n">d</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>

  2129.         <span class="n">data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>

  2130.         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">data</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">&#39;utf-8&#39;</span><span class="p">))</span>

  2131. 

  2132.     <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2133.         <span class="bp">self</span><span class="o">.</span><span class="n">queue</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  2134. 

  2135. <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;pynng&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">propagate</span> <span class="o">=</span> <span class="kc">False</span>

  2136. <span class="n">handler</span> <span class="o">=</span> <span class="n">NNGSocketHandler</span><span class="p">(</span><span class="n">DEFAULT_ADDR</span><span class="p">)</span>

  2137. <span class="c1"># Make sure the process ID is in the output</span>

  2138. <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span>

  2139.                     <span class="n">handlers</span><span class="o">=</span><span class="p">[</span><span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">(),</span> <span class="n">handler</span><span class="p">],</span>

  2140.                     <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(name)10s</span><span class="s1"> </span><span class="si">%(process)6s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  2141. <span class="n">levels</span> <span class="o">=</span> <span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span>

  2142.           <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">)</span>

  2143. <span class="n">logger_names</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;myapp.lib1&#39;</span><span class="p">,</span> <span class="s1">&#39;myapp.lib2&#39;</span><span class="p">)</span>

  2144. <span class="n">msgno</span> <span class="o">=</span> <span class="mi">1</span>

  2145. <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  2146.     <span class="c1"># Just randomly select some loggers and levels and log away</span>

  2147.     <span class="n">level</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">levels</span><span class="p">)</span>

  2148.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">logger_names</span><span class="p">))</span>

  2149.     <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="s1">&#39;Message no. </span><span class="si">%5d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">msgno</span><span class="p">)</span>

  2150.     <span class="n">msgno</span> <span class="o">+=</span> <span class="mi">1</span>

  2151.     <span class="n">delay</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span> <span class="o">*</span> <span class="mi">2</span> <span class="o">+</span> <span class="mf">0.5</span>

  2152.     <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">delay</span><span class="p">)</span>

  2153. </pre></div>

  2154. </div>

  2155. <p>You can run the above two snippets in separate command shells. If we run the

  2156. listener in one shell and run the sender in two separate shells, we should see

  2157. something like the following. In the first sender shell:</p>

  2158. <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>sender.py

  2159. <span class="go">DEBUG         myapp    613 Message no.     1</span>

  2160. <span class="go">WARNING  myapp.lib2    613 Message no.     2</span>

  2161. <span class="go">CRITICAL myapp.lib2    613 Message no.     3</span>

  2162. <span class="go">WARNING  myapp.lib2    613 Message no.     4</span>

  2163. <span class="go">CRITICAL myapp.lib1    613 Message no.     5</span>

  2164. <span class="go">DEBUG         myapp    613 Message no.     6</span>

  2165. <span class="go">CRITICAL myapp.lib1    613 Message no.     7</span>

  2166. <span class="go">INFO     myapp.lib1    613 Message no.     8</span>

  2167. <span class="gp gp-VirtualEnv">(and so on)</span>

  2168. </pre></div>

  2169. </div>

  2170. <p>In the second sender shell:</p>

  2171. <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>sender.py

  2172. <span class="go">INFO     myapp.lib2    657 Message no.     1</span>

  2173. <span class="go">CRITICAL myapp.lib2    657 Message no.     2</span>

  2174. <span class="go">CRITICAL      myapp    657 Message no.     3</span>

  2175. <span class="go">CRITICAL myapp.lib1    657 Message no.     4</span>

  2176. <span class="go">INFO     myapp.lib1    657 Message no.     5</span>

  2177. <span class="go">WARNING  myapp.lib2    657 Message no.     6</span>

  2178. <span class="go">CRITICAL      myapp    657 Message no.     7</span>

  2179. <span class="go">DEBUG    myapp.lib1    657 Message no.     8</span>

  2180. <span class="gp gp-VirtualEnv">(and so on)</span>

  2181. </pre></div>

  2182. </div>

  2183. <p>In the listener shell:</p>

  2184. <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>listener.py

  2185. <span class="go">Press Ctrl-C to stop.</span>

  2186. <span class="go">DEBUG         myapp    613 Message no.     1</span>

  2187. <span class="go">WARNING  myapp.lib2    613 Message no.     2</span>

  2188. <span class="go">INFO     myapp.lib2    657 Message no.     1</span>

  2189. <span class="go">CRITICAL myapp.lib2    613 Message no.     3</span>

  2190. <span class="go">CRITICAL myapp.lib2    657 Message no.     2</span>

  2191. <span class="go">CRITICAL      myapp    657 Message no.     3</span>

  2192. <span class="go">WARNING  myapp.lib2    613 Message no.     4</span>

  2193. <span class="go">CRITICAL myapp.lib1    613 Message no.     5</span>

  2194. <span class="go">CRITICAL myapp.lib1    657 Message no.     4</span>

  2195. <span class="go">INFO     myapp.lib1    657 Message no.     5</span>

  2196. <span class="go">DEBUG         myapp    613 Message no.     6</span>

  2197. <span class="go">WARNING  myapp.lib2    657 Message no.     6</span>

  2198. <span class="go">CRITICAL      myapp    657 Message no.     7</span>

  2199. <span class="go">CRITICAL myapp.lib1    613 Message no.     7</span>

  2200. <span class="go">INFO     myapp.lib1    613 Message no.     8</span>

  2201. <span class="go">DEBUG    myapp.lib1    657 Message no.     8</span>

  2202. <span class="gp gp-VirtualEnv">(and so on)</span>

  2203. </pre></div>

  2204. </div>

  2205. <p>As you can see, the logging from the two sender processes is interleaved in the

  2206. listener’s output.</p>

  2207. </section>

  2208. </section>

  2209. <section id="an-example-dictionary-based-configuration">

  2210. <h2>An example dictionary-based configuration<a class="headerlink" href="#an-example-dictionary-based-configuration" title="Link to this heading">¶</a></h2>

  2211. <p>Below is an example of a logging configuration dictionary - it’s taken from

  2212. the <a class="reference external" href="https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging">documentation on the Django project</a>.

  2213. This dictionary is passed to <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> to put the configuration into effect:</p>

  2214. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">LOGGING</span> <span class="o">=</span> <span class="p">{</span>

  2215.     <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2216.     <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>

  2217.     <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2218.         <span class="s1">&#39;verbose&#39;</span><span class="p">:</span> <span class="p">{</span>

  2219.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">{levelname}</span><span class="s1"> </span><span class="si">{asctime}</span><span class="s1"> </span><span class="si">{module}</span><span class="s1"> </span><span class="si">{process:d}</span><span class="s1"> </span><span class="si">{thread:d}</span><span class="s1"> </span><span class="si">{message}</span><span class="s1">&#39;</span><span class="p">,</span>

  2220.             <span class="s1">&#39;style&#39;</span><span class="p">:</span> <span class="s1">&#39;{&#39;</span><span class="p">,</span>

  2221.         <span class="p">},</span>

  2222.         <span class="s1">&#39;simple&#39;</span><span class="p">:</span> <span class="p">{</span>

  2223.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">{levelname}</span><span class="s1"> </span><span class="si">{message}</span><span class="s1">&#39;</span><span class="p">,</span>

  2224.             <span class="s1">&#39;style&#39;</span><span class="p">:</span> <span class="s1">&#39;{&#39;</span><span class="p">,</span>

  2225.         <span class="p">},</span>

  2226.     <span class="p">},</span>

  2227.     <span class="s1">&#39;filters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2228.         <span class="s1">&#39;special&#39;</span><span class="p">:</span> <span class="p">{</span>

  2229.             <span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="s1">&#39;project.logging.SpecialFilter&#39;</span><span class="p">,</span>

  2230.             <span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;bar&#39;</span><span class="p">,</span>

  2231.         <span class="p">},</span>

  2232.     <span class="p">},</span>

  2233.     <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2234.         <span class="s1">&#39;console&#39;</span><span class="p">:</span> <span class="p">{</span>

  2235.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;INFO&#39;</span><span class="p">,</span>

  2236.             <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  2237.             <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;simple&#39;</span><span class="p">,</span>

  2238.         <span class="p">},</span>

  2239.         <span class="s1">&#39;mail_admins&#39;</span><span class="p">:</span> <span class="p">{</span>

  2240.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;ERROR&#39;</span><span class="p">,</span>

  2241.             <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;django.utils.log.AdminEmailHandler&#39;</span><span class="p">,</span>

  2242.             <span class="s1">&#39;filters&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;special&#39;</span><span class="p">]</span>

  2243.         <span class="p">}</span>

  2244.     <span class="p">},</span>

  2245.     <span class="s1">&#39;loggers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2246.         <span class="s1">&#39;django&#39;</span><span class="p">:</span> <span class="p">{</span>

  2247.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">],</span>

  2248.             <span class="s1">&#39;propagate&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>

  2249.         <span class="p">},</span>

  2250.         <span class="s1">&#39;django.request&#39;</span><span class="p">:</span> <span class="p">{</span>

  2251.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;mail_admins&#39;</span><span class="p">],</span>

  2252.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;ERROR&#39;</span><span class="p">,</span>

  2253.             <span class="s1">&#39;propagate&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>

  2254.         <span class="p">},</span>

  2255.         <span class="s1">&#39;myproject.custom&#39;</span><span class="p">:</span> <span class="p">{</span>

  2256.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">,</span> <span class="s1">&#39;mail_admins&#39;</span><span class="p">],</span>

  2257.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;INFO&#39;</span><span class="p">,</span>

  2258.             <span class="s1">&#39;filters&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;special&#39;</span><span class="p">]</span>

  2259.         <span class="p">}</span>

  2260.     <span class="p">}</span>

  2261. <span class="p">}</span>

  2262. </pre></div>

  2263. </div>

  2264. <p>For more information about this configuration, you can see the <a class="reference external" href="https://docs.djangoproject.com/en/stable/topics/logging/#configuring-logging">relevant

  2265. section</a>

  2266. of the Django documentation.</p>

  2267. </section>

  2268. <section id="using-a-rotator-and-namer-to-customize-log-rotation-processing">

  2269. <span id="cookbook-rotator-namer"></span><h2>Using a rotator and namer to customize log rotation processing<a class="headerlink" href="#using-a-rotator-and-namer-to-customize-log-rotation-processing" title="Link to this heading">¶</a></h2>

  2270. <p>An example of how you can define a namer and rotator is given in the following

  2271. runnable script, which shows gzip compression of the log file:</p>

  2272. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">gzip</span>

  2273. <span class="kn">import</span> <span class="nn">logging</span>

  2274. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  2275. <span class="kn">import</span> <span class="nn">os</span>

  2276. <span class="kn">import</span> <span class="nn">shutil</span>

  2277. 

  2278. <span class="k">def</span> <span class="nf">namer</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>

  2279.     <span class="k">return</span> <span class="n">name</span> <span class="o">+</span> <span class="s2">&quot;.gz&quot;</span>

  2280. 

  2281. <span class="k">def</span> <span class="nf">rotator</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">dest</span><span class="p">):</span>

  2282.     <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f_in</span><span class="p">:</span>

  2283.         <span class="k">with</span> <span class="n">gzip</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f_out</span><span class="p">:</span>

  2284.             <span class="n">shutil</span><span class="o">.</span><span class="n">copyfileobj</span><span class="p">(</span><span class="n">f_in</span><span class="p">,</span> <span class="n">f_out</span><span class="p">)</span>

  2285.     <span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">source</span><span class="p">)</span>

  2286. 

  2287. 

  2288. <span class="n">rh</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">RotatingFileHandler</span><span class="p">(</span><span class="s1">&#39;rotated.log&#39;</span><span class="p">,</span> <span class="n">maxBytes</span><span class="o">=</span><span class="mi">128</span><span class="p">,</span> <span class="n">backupCount</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>

  2289. <span class="n">rh</span><span class="o">.</span><span class="n">rotator</span> <span class="o">=</span> <span class="n">rotator</span>

  2290. <span class="n">rh</span><span class="o">.</span><span class="n">namer</span> <span class="o">=</span> <span class="n">namer</span>

  2291. 

  2292. <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  2293. <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  2294. <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">rh</span><span class="p">)</span>

  2295. <span class="n">f</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  2296. <span class="n">rh</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  2297. <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1000</span><span class="p">):</span>

  2298.     <span class="n">root</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Message no. </span><span class="si">{</span><span class="n">i</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>

  2299. </pre></div>

  2300. </div>

  2301. <p>After running this, you will see six new files, five of which are compressed:</p>

  2302. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ls<span class="w"> </span>rotated.log*

  2303. <span class="go">rotated.log       rotated.log.2.gz  rotated.log.4.gz</span>

  2304. <span class="go">rotated.log.1.gz  rotated.log.3.gz  rotated.log.5.gz</span>

  2305. <span class="gp">$ </span>zcat<span class="w"> </span>rotated.log.1.gz

  2306. <span class="go">2023-01-20 02:28:17,767 Message no. 996</span>

  2307. <span class="go">2023-01-20 02:28:17,767 Message no. 997</span>

  2308. <span class="go">2023-01-20 02:28:17,767 Message no. 998</span>

  2309. </pre></div>

  2310. </div>

  2311. </section>

  2312. <section id="a-more-elaborate-multiprocessing-example">

  2313. <h2>A more elaborate multiprocessing example<a class="headerlink" href="#a-more-elaborate-multiprocessing-example" title="Link to this heading">¶</a></h2>

  2314. <p>The following working example shows how logging can be used with multiprocessing

  2315. using configuration files. The configurations are fairly simple, but serve to

  2316. illustrate how more complex ones could be implemented in a real multiprocessing

  2317. scenario.</p>

  2318. <p>In the example, the main process spawns a listener process and some worker

  2319. processes. Each of the main process, the listener and the workers have three

  2320. separate configurations (the workers all share the same configuration). We can

  2321. see logging in the main process, how the workers log to a QueueHandler and how

  2322. the listener implements a QueueListener and a more complex logging

  2323. configuration, and arranges to dispatch events received via the queue to the

  2324. handlers specified in the configuration. Note that these configurations are

  2325. purely illustrative, but you should be able to adapt this example to your own

  2326. scenario.</p>

  2327. <p>Here’s the script - the docstrings and the comments hopefully explain how it

  2328. works:</p>

  2329. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  2330. <span class="kn">import</span> <span class="nn">logging.config</span>

  2331. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  2332. <span class="kn">from</span> <span class="nn">multiprocessing</span> <span class="kn">import</span> <span class="n">Process</span><span class="p">,</span> <span class="n">Queue</span><span class="p">,</span> <span class="n">Event</span><span class="p">,</span> <span class="n">current_process</span>

  2333. <span class="kn">import</span> <span class="nn">os</span>

  2334. <span class="kn">import</span> <span class="nn">random</span>

  2335. <span class="kn">import</span> <span class="nn">time</span>

  2336. 

  2337. <span class="k">class</span> <span class="nc">MyHandler</span><span class="p">:</span>

  2338. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  2339. <span class="sd">    A simple handler for logging events. It runs in the listener process and</span>

  2340. <span class="sd">    dispatches events to loggers based on the name in the received record,</span>

  2341. <span class="sd">    which then get dispatched, by the logging system, to the handlers</span>

  2342. <span class="sd">    configured for those loggers.</span>

  2343. <span class="sd">    &quot;&quot;&quot;</span>

  2344. 

  2345.     <span class="k">def</span> <span class="nf">handle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  2346.         <span class="k">if</span> <span class="n">record</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s2">&quot;root&quot;</span><span class="p">:</span>

  2347.             <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  2348.         <span class="k">else</span><span class="p">:</span>

  2349.             <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  2350. 

  2351.         <span class="k">if</span> <span class="n">logger</span><span class="o">.</span><span class="n">isEnabledFor</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">levelno</span><span class="p">):</span>

  2352.             <span class="c1"># The process name is transformed just to show that it&#39;s the listener</span>

  2353.             <span class="c1"># doing the logging to files and console</span>

  2354.             <span class="n">record</span><span class="o">.</span><span class="n">processName</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="si">%s</span><span class="s1"> (for </span><span class="si">%s</span><span class="s1">)&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">current_process</span><span class="p">()</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">record</span><span class="o">.</span><span class="n">processName</span><span class="p">)</span>

  2355.             <span class="n">logger</span><span class="o">.</span><span class="n">handle</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  2356. 

  2357. <span class="k">def</span> <span class="nf">listener_process</span><span class="p">(</span><span class="n">q</span><span class="p">,</span> <span class="n">stop_event</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>

  2358. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  2359. <span class="sd">    This could be done in the main process, but is just done in a separate</span>

  2360. <span class="sd">    process for illustrative purposes.</span>

  2361. 

  2362. <span class="sd">    This initialises logging according to the specified configuration,</span>

  2363. <span class="sd">    starts the listener and waits for the main process to signal completion</span>

  2364. <span class="sd">    via the event. The listener is then stopped, and the process exits.</span>

  2365. <span class="sd">    &quot;&quot;&quot;</span>

  2366.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>

  2367.     <span class="n">listener</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">QueueListener</span><span class="p">(</span><span class="n">q</span><span class="p">,</span> <span class="n">MyHandler</span><span class="p">())</span>

  2368.     <span class="n">listener</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2369.     <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">&#39;posix&#39;</span><span class="p">:</span>

  2370.         <span class="c1"># On POSIX, the setup logger will have been configured in the</span>

  2371.         <span class="c1"># parent process, but should have been disabled following the</span>

  2372.         <span class="c1"># dictConfig call.</span>

  2373.         <span class="c1"># On Windows, since fork isn&#39;t used, the setup logger won&#39;t</span>

  2374.         <span class="c1"># exist in the child, so it would be created and the message</span>

  2375.         <span class="c1"># would appear - hence the &quot;if posix&quot; clause.</span>

  2376.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;setup&#39;</span><span class="p">)</span>

  2377.         <span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;Should not appear, because of disabled logger ...&#39;</span><span class="p">)</span>

  2378.     <span class="n">stop_event</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>

  2379.     <span class="n">listener</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>

  2380. 

  2381. <span class="k">def</span> <span class="nf">worker_process</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>

  2382. <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  2383. <span class="sd">    A number of these are spawned for the purpose of illustration. In</span>

  2384. <span class="sd">    practice, they could be a heterogeneous bunch of processes rather than</span>

  2385. <span class="sd">    ones which are identical to each other.</span>

  2386. 

  2387. <span class="sd">    This initialises logging according to the specified configuration,</span>

  2388. <span class="sd">    and logs a hundred messages with random levels to randomly selected</span>

  2389. <span class="sd">    loggers.</span>

  2390. 

  2391. <span class="sd">    A small sleep is added to allow other processes a chance to run. This</span>

  2392. <span class="sd">    is not strictly needed, but it mixes the output from the different</span>

  2393. <span class="sd">    processes a bit more than if it&#39;s left out.</span>

  2394. <span class="sd">    &quot;&quot;&quot;</span>

  2395.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>

  2396.     <span class="n">levels</span> <span class="o">=</span> <span class="p">[</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span>

  2397.               <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">]</span>

  2398.     <span class="n">loggers</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;foo.bar&#39;</span><span class="p">,</span> <span class="s1">&#39;foo.bar.baz&#39;</span><span class="p">,</span>

  2399.                <span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;spam.ham&#39;</span><span class="p">,</span> <span class="s1">&#39;spam.ham.eggs&#39;</span><span class="p">]</span>

  2400.     <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">&#39;posix&#39;</span><span class="p">:</span>

  2401.         <span class="c1"># On POSIX, the setup logger will have been configured in the</span>

  2402.         <span class="c1"># parent process, but should have been disabled following the</span>

  2403.         <span class="c1"># dictConfig call.</span>

  2404.         <span class="c1"># On Windows, since fork isn&#39;t used, the setup logger won&#39;t</span>

  2405.         <span class="c1"># exist in the child, so it would be created and the message</span>

  2406.         <span class="c1"># would appear - hence the &quot;if posix&quot; clause.</span>

  2407.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;setup&#39;</span><span class="p">)</span>

  2408.         <span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;Should not appear, because of disabled logger ...&#39;</span><span class="p">)</span>

  2409.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">100</span><span class="p">):</span>

  2410.         <span class="n">lvl</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">levels</span><span class="p">)</span>

  2411.         <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">loggers</span><span class="p">))</span>

  2412.         <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">lvl</span><span class="p">,</span> <span class="s1">&#39;Message no. </span><span class="si">%d</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>

  2413.         <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.01</span><span class="p">)</span>

  2414. 

  2415. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  2416.     <span class="n">q</span> <span class="o">=</span> <span class="n">Queue</span><span class="p">()</span>

  2417.     <span class="c1"># The main process gets a simple configuration which prints to the console.</span>

  2418.     <span class="n">config_initial</span> <span class="o">=</span> <span class="p">{</span>

  2419.         <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2420.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2421.             <span class="s1">&#39;console&#39;</span><span class="p">:</span> <span class="p">{</span>

  2422.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  2423.                 <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;INFO&#39;</span>

  2424.             <span class="p">}</span>

  2425.         <span class="p">},</span>

  2426.         <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2427.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">],</span>

  2428.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span>

  2429.         <span class="p">}</span>

  2430.     <span class="p">}</span>

  2431.     <span class="c1"># The worker process configuration is just a QueueHandler attached to the</span>

  2432.     <span class="c1"># root logger, which allows all messages to be sent to the queue.</span>

  2433.     <span class="c1"># We disable existing loggers to disable the &quot;setup&quot; logger used in the</span>

  2434.     <span class="c1"># parent process. This is needed on POSIX because the logger will</span>

  2435.     <span class="c1"># be there in the child following a fork().</span>

  2436.     <span class="n">config_worker</span> <span class="o">=</span> <span class="p">{</span>

  2437.         <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2438.         <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>

  2439.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2440.             <span class="s1">&#39;queue&#39;</span><span class="p">:</span> <span class="p">{</span>

  2441.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.handlers.QueueHandler&#39;</span><span class="p">,</span>

  2442.                 <span class="s1">&#39;queue&#39;</span><span class="p">:</span> <span class="n">q</span>

  2443.             <span class="p">}</span>

  2444.         <span class="p">},</span>

  2445.         <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2446.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;queue&#39;</span><span class="p">],</span>

  2447.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span>

  2448.         <span class="p">}</span>

  2449.     <span class="p">}</span>

  2450.     <span class="c1"># The listener process configuration shows that the full flexibility of</span>

  2451.     <span class="c1"># logging configuration is available to dispatch events to handlers however</span>

  2452.     <span class="c1"># you want.</span>

  2453.     <span class="c1"># We disable existing loggers to disable the &quot;setup&quot; logger used in the</span>

  2454.     <span class="c1"># parent process. This is needed on POSIX because the logger will</span>

  2455.     <span class="c1"># be there in the child following a fork().</span>

  2456.     <span class="n">config_listener</span> <span class="o">=</span> <span class="p">{</span>

  2457.         <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2458.         <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>

  2459.         <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2460.             <span class="s1">&#39;detailed&#39;</span><span class="p">:</span> <span class="p">{</span>

  2461.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.Formatter&#39;</span><span class="p">,</span>

  2462.                 <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(name)-15s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(processName)-10s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  2463.             <span class="p">},</span>

  2464.             <span class="s1">&#39;simple&#39;</span><span class="p">:</span> <span class="p">{</span>

  2465.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.Formatter&#39;</span><span class="p">,</span>

  2466.                 <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(name)-15s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(processName)-10s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  2467.             <span class="p">}</span>

  2468.         <span class="p">},</span>

  2469.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2470.             <span class="s1">&#39;console&#39;</span><span class="p">:</span> <span class="p">{</span>

  2471.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  2472.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;simple&#39;</span><span class="p">,</span>

  2473.                 <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;INFO&#39;</span>

  2474.             <span class="p">},</span>

  2475.             <span class="s1">&#39;file&#39;</span><span class="p">:</span> <span class="p">{</span>

  2476.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  2477.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog.log&#39;</span><span class="p">,</span>

  2478.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  2479.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span>

  2480.             <span class="p">},</span>

  2481.             <span class="s1">&#39;foofile&#39;</span><span class="p">:</span> <span class="p">{</span>

  2482.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  2483.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog-foo.log&#39;</span><span class="p">,</span>

  2484.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  2485.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span>

  2486.             <span class="p">},</span>

  2487.             <span class="s1">&#39;errors&#39;</span><span class="p">:</span> <span class="p">{</span>

  2488.                 <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.FileHandler&#39;</span><span class="p">,</span>

  2489.                 <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;mplog-errors.log&#39;</span><span class="p">,</span>

  2490.                 <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  2491.                 <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;detailed&#39;</span><span class="p">,</span>

  2492.                 <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;ERROR&#39;</span>

  2493.             <span class="p">}</span>

  2494.         <span class="p">},</span>

  2495.         <span class="s1">&#39;loggers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2496.             <span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="p">{</span>

  2497.                 <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;foofile&#39;</span><span class="p">]</span>

  2498.             <span class="p">}</span>

  2499.         <span class="p">},</span>

  2500.         <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2501.             <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">,</span> <span class="s1">&#39;file&#39;</span><span class="p">,</span> <span class="s1">&#39;errors&#39;</span><span class="p">],</span>

  2502.             <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span>

  2503.         <span class="p">}</span>

  2504.     <span class="p">}</span>

  2505.     <span class="c1"># Log some initial events, just to show that logging in the parent works</span>

  2506.     <span class="c1"># normally.</span>

  2507.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">config_initial</span><span class="p">)</span>

  2508.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;setup&#39;</span><span class="p">)</span>

  2509.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;About to create workers ...&#39;</span><span class="p">)</span>

  2510.     <span class="n">workers</span> <span class="o">=</span> <span class="p">[]</span>

  2511.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">):</span>

  2512.         <span class="n">wp</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">worker_process</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">&#39;worker </span><span class="si">%d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">),</span>

  2513.                      <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">config_worker</span><span class="p">,))</span>

  2514.         <span class="n">workers</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">wp</span><span class="p">)</span>

  2515.         <span class="n">wp</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2516.         <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Started worker: </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">wp</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  2517.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;About to create listener ...&#39;</span><span class="p">)</span>

  2518.     <span class="n">stop_event</span> <span class="o">=</span> <span class="n">Event</span><span class="p">()</span>

  2519.     <span class="n">lp</span> <span class="o">=</span> <span class="n">Process</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">listener_process</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">&#39;listener&#39;</span><span class="p">,</span>

  2520.                  <span class="n">args</span><span class="o">=</span><span class="p">(</span><span class="n">q</span><span class="p">,</span> <span class="n">stop_event</span><span class="p">,</span> <span class="n">config_listener</span><span class="p">))</span>

  2521.     <span class="n">lp</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2522.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Started listener&#39;</span><span class="p">)</span>

  2523.     <span class="c1"># We now hang around for the workers to finish their work.</span>

  2524.     <span class="k">for</span> <span class="n">wp</span> <span class="ow">in</span> <span class="n">workers</span><span class="p">:</span>

  2525.         <span class="n">wp</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  2526.     <span class="c1"># Workers all done, listening can now stop.</span>

  2527.     <span class="c1"># Logging in the parent still works normally.</span>

  2528.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Telling listener to stop ...&#39;</span><span class="p">)</span>

  2529.     <span class="n">stop_event</span><span class="o">.</span><span class="n">set</span><span class="p">()</span>

  2530.     <span class="n">lp</span><span class="o">.</span><span class="n">join</span><span class="p">()</span>

  2531.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;All done.&#39;</span><span class="p">)</span>

  2532. 

  2533. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  2534.     <span class="n">main</span><span class="p">()</span>

  2535. </pre></div>

  2536. </div>

  2537. </section>

  2538. <section id="inserting-a-bom-into-messages-sent-to-a-sysloghandler">

  2539. <h2>Inserting a BOM into messages sent to a SysLogHandler<a class="headerlink" href="#inserting-a-bom-into-messages-sent-to-a-sysloghandler" title="Link to this heading">¶</a></h2>

  2540. <p><span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5424.html"><strong>RFC 5424</strong></a> requires that a

  2541. Unicode message be sent to a syslog daemon as a set of bytes which have the

  2542. following structure: an optional pure-ASCII component, followed by a UTF-8 Byte

  2543. Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the

  2544. <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5424.html#section-6"><strong>relevant section of the specification</strong></a>.)</p>

  2545. <p>In Python 3.1, code was added to

  2546. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SysLogHandler" title="logging.handlers.SysLogHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SysLogHandler</span></code></a> to insert a BOM into the message, but

  2547. unfortunately, it was implemented incorrectly, with the BOM appearing at the

  2548. beginning of the message and hence not allowing any pure-ASCII component to

  2549. appear before it.</p>

  2550. <p>As this behaviour is broken, the incorrect BOM insertion code is being removed

  2551. from Python 3.2.4 and later. However, it is not being replaced, and if you

  2552. want to produce <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5424.html"><strong>RFC 5424</strong></a>-compliant messages which include a BOM, an optional

  2553. pure-ASCII sequence before it and arbitrary Unicode after it, encoded using

  2554. UTF-8, then you need to do the following:</p>

  2555. <ol class="arabic">

  2556. <li><p>Attach a <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> instance to your

  2557. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SysLogHandler" title="logging.handlers.SysLogHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SysLogHandler</span></code></a> instance, with a format string

  2558. such as:</p>

  2559. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;ASCII section</span><span class="se">\ufeff</span><span class="s1">Unicode section&#39;</span>

  2560. </pre></div>

  2561. </div>

  2562. <p>The Unicode code point U+FEFF, when encoded using UTF-8, will be

  2563. encoded as a UTF-8 BOM – the byte-string <code class="docutils literal notranslate"><span class="pre">b'\xef\xbb\xbf'</span></code>.</p>

  2564. </li>

  2565. <li><p>Replace the ASCII section with whatever placeholders you like, but make sure

  2566. that the data that appears in there after substitution is always ASCII (that

  2567. way, it will remain unchanged after UTF-8 encoding).</p></li>

  2568. <li><p>Replace the Unicode section with whatever placeholders you like; if the data

  2569. which appears there after substitution contains characters outside the ASCII

  2570. range, that’s fine – it will be encoded using UTF-8.</p></li>

  2571. </ol>

  2572. <p>The formatted message <em>will</em> be encoded using UTF-8 encoding by

  2573. <code class="docutils literal notranslate"><span class="pre">SysLogHandler</span></code>. If you follow the above rules, you should be able to produce

  2574. <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5424.html"><strong>RFC 5424</strong></a>-compliant messages. If you don’t, logging may not complain, but your

  2575. messages will not be RFC 5424-compliant, and your syslog daemon may complain.</p>

  2576. </section>

  2577. <section id="implementing-structured-logging">

  2578. <h2>Implementing structured logging<a class="headerlink" href="#implementing-structured-logging" title="Link to this heading">¶</a></h2>

  2579. <p>Although most logging messages are intended for reading by humans, and thus not

  2580. readily machine-parseable, there might be circumstances where you want to output

  2581. messages in a structured format which <em>is</em> capable of being parsed by a program

  2582. (without needing complex regular expressions to parse the log message). This is

  2583. straightforward to achieve using the logging package. There are a number of

  2584. ways in which this could be achieved, but the following is a simple approach

  2585. which uses JSON to serialise the event in a machine-parseable manner:</p>

  2586. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">json</span>

  2587. <span class="kn">import</span> <span class="nn">logging</span>

  2588. 

  2589. <span class="k">class</span> <span class="nc">StructuredMessage</span><span class="p">:</span>

  2590.     <span class="k">def</span> <span class="fm">__init__</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="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2591.         <span class="bp">self</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="n">message</span>

  2592.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  2593. 

  2594.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2595.         <span class="k">return</span> <span class="s1">&#39;</span><span class="si">%s</span><span class="s1"> &gt;&gt;&gt; </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="p">,</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">))</span>

  2596. 

  2597. <span class="n">_</span> <span class="o">=</span> <span class="n">StructuredMessage</span>   <span class="c1"># optional, to improve readability</span>

  2598. 

  2599. <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  2600. <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s1">&#39;message 1&#39;</span><span class="p">,</span> <span class="n">foo</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;baz&#39;</span><span class="p">,</span> <span class="n">num</span><span class="o">=</span><span class="mi">123</span><span class="p">,</span> <span class="n">fnum</span><span class="o">=</span><span class="mf">123.456</span><span class="p">))</span>

  2601. </pre></div>

  2602. </div>

  2603. <p>If the above script is run, it prints:</p>

  2604. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>message 1 &gt;&gt;&gt; {&quot;fnum&quot;: 123.456, &quot;num&quot;: 123, &quot;bar&quot;: &quot;baz&quot;, &quot;foo&quot;: &quot;bar&quot;}

  2605. </pre></div>

  2606. </div>

  2607. <p>Note that the order of items might be different according to the version of

  2608. Python used.</p>

  2609. <p>If you need more specialised processing, you can use a custom JSON encoder,

  2610. as in the following complete example:</p>

  2611. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">json</span>

  2612. <span class="kn">import</span> <span class="nn">logging</span>

  2613. 

  2614. 

  2615. <span class="k">class</span> <span class="nc">Encoder</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">JSONEncoder</span><span class="p">):</span>

  2616.     <span class="k">def</span> <span class="nf">default</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">o</span><span class="p">):</span>

  2617.         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">o</span><span class="p">,</span> <span class="nb">set</span><span class="p">):</span>

  2618.             <span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">o</span><span class="p">)</span>

  2619.         <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">o</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>

  2620.             <span class="k">return</span> <span class="n">o</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">&#39;unicode_escape&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">&#39;ascii&#39;</span><span class="p">)</span>

  2621.         <span class="k">return</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">default</span><span class="p">(</span><span class="n">o</span><span class="p">)</span>

  2622. 

  2623. <span class="k">class</span> <span class="nc">StructuredMessage</span><span class="p">:</span>

  2624.     <span class="k">def</span> <span class="fm">__init__</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="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2625.         <span class="bp">self</span><span class="o">.</span><span class="n">message</span> <span class="o">=</span> <span class="n">message</span>

  2626.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  2627. 

  2628.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2629.         <span class="n">s</span> <span class="o">=</span> <span class="n">Encoder</span><span class="p">()</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span>

  2630.         <span class="k">return</span> <span class="s1">&#39;</span><span class="si">%s</span><span class="s1"> &gt;&gt;&gt; </span><span class="si">%s</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">message</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>

  2631. 

  2632. <span class="n">_</span> <span class="o">=</span> <span class="n">StructuredMessage</span>   <span class="c1"># optional, to improve readability</span>

  2633. 

  2634. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  2635.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  2636.     <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s1">&#39;message 1&#39;</span><span class="p">,</span> <span class="n">set_value</span><span class="o">=</span><span class="p">{</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">},</span> <span class="n">snowman</span><span class="o">=</span><span class="s1">&#39;</span><span class="se">\u2603</span><span class="s1">&#39;</span><span class="p">))</span>

  2637. 

  2638. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  2639.     <span class="n">main</span><span class="p">()</span>

  2640. </pre></div>

  2641. </div>

  2642. <p>When the above script is run, it prints:</p>

  2643. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>message 1 &gt;&gt;&gt; {&quot;snowman&quot;: &quot;\u2603&quot;, &quot;set_value&quot;: [1, 2, 3]}

  2644. </pre></div>

  2645. </div>

  2646. <p>Note that the order of items might be different according to the version of

  2647. Python used.</p>

  2648. </section>

  2649. <section id="customizing-handlers-with-dictconfig">

  2650. <span id="custom-handlers"></span><h2>Customizing handlers with <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a><a class="headerlink" href="#customizing-handlers-with-dictconfig" title="Link to this heading">¶</a></h2>

  2651. <p>There are times when you want to customize logging handlers in particular ways,

  2652. and if you use <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> you may be able to do this without

  2653. subclassing. As an example, consider that you may want to set the ownership of a

  2654. log file. On POSIX, this is easily done using <a class="reference internal" href="../library/shutil.html#shutil.chown" title="shutil.chown"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.chown()</span></code></a>, but the file

  2655. handlers in the stdlib don’t offer built-in support. You can customize handler

  2656. creation using a plain function such as:</p>

  2657. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">owned_file_handler</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">owner</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  2658.     <span class="k">if</span> <span class="n">owner</span><span class="p">:</span>

  2659.         <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>

  2660.             <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s1">&#39;a&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  2661.         <span class="n">shutil</span><span class="o">.</span><span class="n">chown</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="o">*</span><span class="n">owner</span><span class="p">)</span>

  2662.     <span class="k">return</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">encoding</span><span class="p">)</span>

  2663. </pre></div>

  2664. </div>

  2665. <p>You can then specify, in a logging configuration passed to <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a>,

  2666. that a logging handler be created by calling this function:</p>

  2667. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">LOGGING</span> <span class="o">=</span> <span class="p">{</span>

  2668.     <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2669.     <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>

  2670.     <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2671.         <span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="p">{</span>

  2672.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(levelname)s</span><span class="s1"> </span><span class="si">%(name)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  2673.         <span class="p">},</span>

  2674.     <span class="p">},</span>

  2675.     <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2676.         <span class="s1">&#39;file&#39;</span><span class="p">:{</span>

  2677.             <span class="c1"># The values below are popped from this dictionary and</span>

  2678.             <span class="c1"># used to create the handler, set the handler&#39;s level and</span>

  2679.             <span class="c1"># its formatter.</span>

  2680.             <span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="n">owned_file_handler</span><span class="p">,</span>

  2681.             <span class="s1">&#39;level&#39;</span><span class="p">:</span><span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  2682.             <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;default&#39;</span><span class="p">,</span>

  2683.             <span class="c1"># The values below are passed to the handler creator callable</span>

  2684.             <span class="c1"># as keyword arguments.</span>

  2685.             <span class="s1">&#39;owner&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;pulse&#39;</span><span class="p">,</span> <span class="s1">&#39;pulse&#39;</span><span class="p">],</span>

  2686.             <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;chowntest.log&#39;</span><span class="p">,</span>

  2687.             <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  2688.             <span class="s1">&#39;encoding&#39;</span><span class="p">:</span> <span class="s1">&#39;utf-8&#39;</span><span class="p">,</span>

  2689.         <span class="p">},</span>

  2690.     <span class="p">},</span>

  2691.     <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2692.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;file&#39;</span><span class="p">],</span>

  2693.         <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  2694.     <span class="p">},</span>

  2695. <span class="p">}</span>

  2696. </pre></div>

  2697. </div>

  2698. <p>In this example I am setting the ownership using the <code class="docutils literal notranslate"><span class="pre">pulse</span></code> user and group,

  2699. just for the purposes of illustration. Putting it together into a working

  2700. script, <code class="docutils literal notranslate"><span class="pre">chowntest.py</span></code>:</p>

  2701. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span><span class="o">,</span> <span class="nn">logging.config</span><span class="o">,</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">shutil</span>

  2702. 

  2703. <span class="k">def</span> <span class="nf">owned_file_handler</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">owner</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  2704.     <span class="k">if</span> <span class="n">owner</span><span class="p">:</span>

  2705.         <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>

  2706.             <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s1">&#39;a&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  2707.         <span class="n">shutil</span><span class="o">.</span><span class="n">chown</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="o">*</span><span class="n">owner</span><span class="p">)</span>

  2708.     <span class="k">return</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">encoding</span><span class="p">)</span>

  2709. 

  2710. <span class="n">LOGGING</span> <span class="o">=</span> <span class="p">{</span>

  2711.     <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2712.     <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>

  2713.     <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2714.         <span class="s1">&#39;default&#39;</span><span class="p">:</span> <span class="p">{</span>

  2715.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(levelname)s</span><span class="s1"> </span><span class="si">%(name)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  2716.         <span class="p">},</span>

  2717.     <span class="p">},</span>

  2718.     <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2719.         <span class="s1">&#39;file&#39;</span><span class="p">:{</span>

  2720.             <span class="c1"># The values below are popped from this dictionary and</span>

  2721.             <span class="c1"># used to create the handler, set the handler&#39;s level and</span>

  2722.             <span class="c1"># its formatter.</span>

  2723.             <span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="n">owned_file_handler</span><span class="p">,</span>

  2724.             <span class="s1">&#39;level&#39;</span><span class="p">:</span><span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  2725.             <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;default&#39;</span><span class="p">,</span>

  2726.             <span class="c1"># The values below are passed to the handler creator callable</span>

  2727.             <span class="c1"># as keyword arguments.</span>

  2728.             <span class="s1">&#39;owner&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;pulse&#39;</span><span class="p">,</span> <span class="s1">&#39;pulse&#39;</span><span class="p">],</span>

  2729.             <span class="s1">&#39;filename&#39;</span><span class="p">:</span> <span class="s1">&#39;chowntest.log&#39;</span><span class="p">,</span>

  2730.             <span class="s1">&#39;mode&#39;</span><span class="p">:</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span>

  2731.             <span class="s1">&#39;encoding&#39;</span><span class="p">:</span> <span class="s1">&#39;utf-8&#39;</span><span class="p">,</span>

  2732.         <span class="p">},</span>

  2733.     <span class="p">},</span>

  2734.     <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2735.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;file&#39;</span><span class="p">],</span>

  2736.         <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  2737.     <span class="p">},</span>

  2738. <span class="p">}</span>

  2739. 

  2740. <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">LOGGING</span><span class="p">)</span>

  2741. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;mylogger&#39;</span><span class="p">)</span>

  2742. <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;A debug message&#39;</span><span class="p">)</span>

  2743. </pre></div>

  2744. </div>

  2745. <p>To run this, you will probably need to run as <code class="docutils literal notranslate"><span class="pre">root</span></code>:</p>

  2746. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>sudo<span class="w"> </span>python3.3<span class="w"> </span>chowntest.py

  2747. <span class="gp">$ </span>cat<span class="w"> </span>chowntest.log

  2748. <span class="go">2013-11-05 09:34:51,128 DEBUG mylogger A debug message</span>

  2749. <span class="gp">$ </span>ls<span class="w"> </span>-l<span class="w"> </span>chowntest.log

  2750. <span class="go">-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log</span>

  2751. </pre></div>

  2752. </div>

  2753. <p>Note that this example uses Python 3.3 because that’s where <a class="reference internal" href="../library/shutil.html#shutil.chown" title="shutil.chown"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.chown()</span></code></a>

  2754. makes an appearance. This approach should work with any Python version that

  2755. supports <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> - namely, Python 2.7, 3.2 or later. With pre-3.3

  2756. versions, you would need to implement the actual ownership change using e.g.

  2757. <a class="reference internal" href="../library/os.html#os.chown" title="os.chown"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.chown()</span></code></a>.</p>

  2758. <p>In practice, the handler-creating function may be in a utility module somewhere

  2759. in your project. Instead of the line in the configuration:</p>

  2760. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="n">owned_file_handler</span><span class="p">,</span>

  2761. </pre></div>

  2762. </div>

  2763. <p>you could use e.g.:</p>

  2764. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="s1">&#39;ext://project.util.owned_file_handler&#39;</span><span class="p">,</span>

  2765. </pre></div>

  2766. </div>

  2767. <p>where <code class="docutils literal notranslate"><span class="pre">project.util</span></code> can be replaced with the actual name of the package

  2768. where the function resides. In the above working script, using

  2769. <code class="docutils literal notranslate"><span class="pre">'ext://__main__.owned_file_handler'</span></code> should work. Here, the actual callable

  2770. is resolved by <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> from the <code class="docutils literal notranslate"><span class="pre">ext://</span></code> specification.</p>

  2771. <p>This example hopefully also points the way to how you could implement other

  2772. types of file change - e.g. setting specific POSIX permission bits - in the

  2773. same way, using <a class="reference internal" href="../library/os.html#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.chmod()</span></code></a>.</p>

  2774. <p>Of course, the approach could also be extended to types of handler other than a

  2775. <a class="reference internal" href="../library/logging.handlers.html#logging.FileHandler" title="logging.FileHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileHandler</span></code></a> - for example, one of the rotating file handlers,

  2776. or a different type of handler altogether.</p>

  2777. </section>

  2778. <section id="using-particular-formatting-styles-throughout-your-application">

  2779. <span id="formatting-styles"></span><h2>Using particular formatting styles throughout your application<a class="headerlink" href="#using-particular-formatting-styles-throughout-your-application" title="Link to this heading">¶</a></h2>

  2780. <p>In Python 3.2, the <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> gained a <code class="docutils literal notranslate"><span class="pre">style</span></code> keyword

  2781. parameter which, while defaulting to <code class="docutils literal notranslate"><span class="pre">%</span></code> for backward compatibility, allowed

  2782. the specification of <code class="docutils literal notranslate"><span class="pre">{</span></code> or <code class="docutils literal notranslate"><span class="pre">$</span></code> to support the formatting approaches

  2783. supported by <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> and <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>. Note that this

  2784. governs the formatting of logging messages for final output to logs, and is

  2785. completely orthogonal to how an individual logging message is constructed.</p>

  2786. <p>Logging calls (<a class="reference internal" href="../library/logging.html#logging.Logger.debug" title="logging.Logger.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="../library/logging.html#logging.Logger.info" title="logging.Logger.info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code></a> etc.) only take

  2787. positional parameters for the actual logging message itself, with keyword

  2788. parameters used only for determining options for how to handle the logging call

  2789. (e.g. the <code class="docutils literal notranslate"><span class="pre">exc_info</span></code> keyword parameter to indicate that traceback information

  2790. should be logged, or the <code class="docutils literal notranslate"><span class="pre">extra</span></code> keyword parameter to indicate additional

  2791. contextual information to be added to the log). So you cannot directly make

  2792. logging calls using <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a> or <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a> syntax,

  2793. because internally the logging package uses %-formatting to merge the format

  2794. string and the variable arguments. There would be no changing this while preserving

  2795. backward compatibility, since all logging calls which are out there in existing

  2796. code will be using %-format strings.</p>

  2797. <p>There have been suggestions to associate format styles with specific loggers,

  2798. but that approach also runs into backward compatibility problems because any

  2799. existing code could be using a given logger name and using %-formatting.</p>

  2800. <p>For logging to work interoperably between any third-party libraries and your

  2801. code, decisions about formatting need to be made at the level of the

  2802. individual logging call. This opens up a couple of ways in which alternative

  2803. formatting styles can be accommodated.</p>

  2804. <section id="using-logrecord-factories">

  2805. <h3>Using LogRecord factories<a class="headerlink" href="#using-logrecord-factories" title="Link to this heading">¶</a></h3>

  2806. <p>In Python 3.2, along with the <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> changes mentioned

  2807. above, the logging package gained the ability to allow users to set their own

  2808. <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> subclasses, using the <a class="reference internal" href="../library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> function.

  2809. You can use this to set your own subclass of <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>, which does the

  2810. Right Thing by overriding the <a class="reference internal" href="../library/logging.html#logging.LogRecord.getMessage" title="logging.LogRecord.getMessage"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getMessage()</span></code></a> method. The base

  2811. class implementation of this method is where the <code class="docutils literal notranslate"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code> formatting

  2812. happens, and where you can substitute your alternate formatting; however, you

  2813. should be careful to support all formatting styles and allow %-formatting as

  2814. the default, to ensure interoperability with other code. Care should also be

  2815. taken to call <code class="docutils literal notranslate"><span class="pre">str(self.msg)</span></code>, just as the base implementation does.</p>

  2816. <p>Refer to the reference documentation on <a class="reference internal" href="../library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> and

  2817. <a class="reference internal" href="../library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> for more information.</p>

  2818. </section>

  2819. <section id="using-custom-message-objects">

  2820. <h3>Using custom message objects<a class="headerlink" href="#using-custom-message-objects" title="Link to this heading">¶</a></h3>

  2821. <p>There is another, perhaps simpler way that you can use {}- and $- formatting to

  2822. construct your individual log messages. You may recall (from

  2823. <a class="reference internal" href="logging.html#arbitrary-object-messages"><span class="std std-ref">Using arbitrary objects as messages</span></a>) that when logging you can use an arbitrary

  2824. object as a message format string, and that the logging package will call

  2825. <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> on that object to get the actual format string. Consider the

  2826. following two classes:</p>

  2827. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BraceMessage</span><span class="p">:</span>

  2828.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2829.         <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span>

  2830.         <span class="bp">self</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="n">args</span>

  2831.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  2832. 

  2833.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2834.         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="o">*</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span>

  2835. 

  2836. <span class="k">class</span> <span class="nc">DollarMessage</span><span class="p">:</span>

  2837.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  2838.         <span class="bp">self</span><span class="o">.</span><span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span>

  2839.         <span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span> <span class="o">=</span> <span class="n">kwargs</span>

  2840. 

  2841.     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2842.         <span class="kn">from</span> <span class="nn">string</span> <span class="kn">import</span> <span class="n">Template</span>

  2843.         <span class="k">return</span> <span class="n">Template</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fmt</span><span class="p">)</span><span class="o">.</span><span class="n">substitute</span><span class="p">(</span><span class="o">**</span><span class="bp">self</span><span class="o">.</span><span class="n">kwargs</span><span class="p">)</span>

  2844. </pre></div>

  2845. </div>

  2846. <p>Either of these can be used in place of a format string, to allow {}- or

  2847. $-formatting to be used to build the actual “message” part which appears in the

  2848. formatted log output in place of “%(message)s” or “{message}” or “$message”.

  2849. If you find it a little unwieldy to use the class names whenever you want to log

  2850. something, you can make it more palatable if you use an alias such as <code class="docutils literal notranslate"><span class="pre">M</span></code> or

  2851. <code class="docutils literal notranslate"><span class="pre">_</span></code> for the message (or perhaps <code class="docutils literal notranslate"><span class="pre">__</span></code>, if you are using <code class="docutils literal notranslate"><span class="pre">_</span></code> for

  2852. localization).</p>

  2853. <p>Examples of this approach are given below. Firstly, formatting with

  2854. <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a>:</p>

  2855. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">__</span> <span class="o">=</span> <span class="n">BraceMessage</span>

  2856. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with </span><span class="si">{0}</span><span class="s1"> </span><span class="si">{1}</span><span class="s1">&#39;</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;placeholders&#39;</span><span class="p">))</span>

  2857. <span class="go">Message with 2 placeholders</span>

  2858. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Point</span><span class="p">:</span> <span class="k">pass</span>

  2859. <span class="gp">...</span>

  2860. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Point</span><span class="p">()</span>

  2861. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mf">0.5</span>

  2862. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="mf">0.5</span>

  2863. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with coordinates: (</span><span class="si">{point.x:.2f}</span><span class="s1">, </span><span class="si">{point.y:.2f}</span><span class="s1">)&#39;</span><span class="p">,</span> <span class="n">point</span><span class="o">=</span><span class="n">p</span><span class="p">))</span>

  2864. <span class="go">Message with coordinates: (0.50, 0.50)</span>

  2865. </pre></div>

  2866. </div>

  2867. <p>Secondly, formatting with <a class="reference internal" href="../library/string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>:</p>

  2868. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">__</span> <span class="o">=</span> <span class="n">DollarMessage</span>

  2869. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">__</span><span class="p">(</span><span class="s1">&#39;Message with $num $what&#39;</span><span class="p">,</span> <span class="n">num</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">what</span><span class="o">=</span><span class="s1">&#39;placeholders&#39;</span><span class="p">))</span>

  2870. <span class="go">Message with 2 placeholders</span>

  2871. <span class="gp">&gt;&gt;&gt;</span>

  2872. </pre></div>

  2873. </div>

  2874. <p>One thing to note is that you pay no significant performance penalty with this

  2875. approach: the actual formatting happens not when you make the logging call, but

  2876. when (and if) the logged message is actually about to be output to a log by a

  2877. handler. So the only slightly unusual thing which might trip you up is that the

  2878. parentheses go around the format string and the arguments, not just the format

  2879. string. That’s because the __ notation is just syntax sugar for a constructor

  2880. call to one of the <code class="samp docutils literal notranslate"><em><span class="pre">XXX</span></em><span class="pre">Message</span></code> classes shown above.</p>

  2881. </section>

  2882. </section>

  2883. <section id="configuring-filters-with-dictconfig">

  2884. <span id="filters-dictconfig"></span><h2>Configuring filters with <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a><a class="headerlink" href="#configuring-filters-with-dictconfig" title="Link to this heading">¶</a></h2>

  2885. <p>You <em>can</em> configure filters using <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a>, though it

  2886. might not be obvious at first glance how to do it (hence this recipe). Since

  2887. <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> is the only filter class included in the standard

  2888. library, and it is unlikely to cater to many requirements (it’s only there as a

  2889. base class), you will typically need to define your own <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a>

  2890. subclass with an overridden <a class="reference internal" href="../library/logging.html#logging.Filter.filter" title="logging.Filter.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a> method. To do this,

  2891. specify the <code class="docutils literal notranslate"><span class="pre">()</span></code> key in the configuration dictionary for the filter,

  2892. specifying a callable which will be used to create the filter (a class is the

  2893. most obvious, but you can provide any callable which returns a

  2894. <a class="reference internal" href="../library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> instance). Here is a complete example:</p>

  2895. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  2896. <span class="kn">import</span> <span class="nn">logging.config</span>

  2897. <span class="kn">import</span> <span class="nn">sys</span>

  2898. 

  2899. <span class="k">class</span> <span class="nc">MyFilter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Filter</span><span class="p">):</span>

  2900.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">param</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  2901.         <span class="bp">self</span><span class="o">.</span><span class="n">param</span> <span class="o">=</span> <span class="n">param</span>

  2902. 

  2903.     <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  2904.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">param</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  2905.             <span class="n">allow</span> <span class="o">=</span> <span class="kc">True</span>

  2906.         <span class="k">else</span><span class="p">:</span>

  2907.             <span class="n">allow</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">param</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">record</span><span class="o">.</span><span class="n">msg</span>

  2908.         <span class="k">if</span> <span class="n">allow</span><span class="p">:</span>

  2909.             <span class="n">record</span><span class="o">.</span><span class="n">msg</span> <span class="o">=</span> <span class="s1">&#39;changed: &#39;</span> <span class="o">+</span> <span class="n">record</span><span class="o">.</span><span class="n">msg</span>

  2910.         <span class="k">return</span> <span class="n">allow</span>

  2911. 

  2912. <span class="n">LOGGING</span> <span class="o">=</span> <span class="p">{</span>

  2913.     <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  2914.     <span class="s1">&#39;filters&#39;</span><span class="p">:</span> <span class="p">{</span>

  2915.         <span class="s1">&#39;myfilter&#39;</span><span class="p">:</span> <span class="p">{</span>

  2916.             <span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="n">MyFilter</span><span class="p">,</span>

  2917.             <span class="s1">&#39;param&#39;</span><span class="p">:</span> <span class="s1">&#39;noshow&#39;</span><span class="p">,</span>

  2918.         <span class="p">}</span>

  2919.     <span class="p">},</span>

  2920.     <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  2921.         <span class="s1">&#39;console&#39;</span><span class="p">:</span> <span class="p">{</span>

  2922.             <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  2923.             <span class="s1">&#39;filters&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;myfilter&#39;</span><span class="p">]</span>

  2924.         <span class="p">}</span>

  2925.     <span class="p">},</span>

  2926.     <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  2927.         <span class="s1">&#39;level&#39;</span><span class="p">:</span> <span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span>

  2928.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console&#39;</span><span class="p">]</span>

  2929.     <span class="p">},</span>

  2930. <span class="p">}</span>

  2931. 

  2932. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  2933.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">LOGGING</span><span class="p">)</span>

  2934.     <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)</span>

  2935.     <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;hello - noshow&#39;</span><span class="p">)</span>

  2936. </pre></div>

  2937. </div>

  2938. <p>This example shows how you can pass configuration data to the callable which

  2939. constructs the instance, in the form of keyword parameters. When run, the above

  2940. script will print:</p>

  2941. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>changed: hello

  2942. </pre></div>

  2943. </div>

  2944. <p>which shows that the filter is working as configured.</p>

  2945. <p>A couple of extra points to note:</p>

  2946. <ul class="simple">

  2947. <li><p>If you can’t refer to the callable directly in the configuration (e.g. if it

  2948. lives in a different module, and you can’t import it directly where the

  2949. configuration dictionary is), you can use the form <code class="docutils literal notranslate"><span class="pre">ext://...</span></code> as described

  2950. in <a class="reference internal" href="../library/logging.config.html#logging-config-dict-externalobj"><span class="std std-ref">Access to external objects</span></a>. For example, you could have used

  2951. the text <code class="docutils literal notranslate"><span class="pre">'ext://__main__.MyFilter'</span></code> instead of <code class="docutils literal notranslate"><span class="pre">MyFilter</span></code> in the above

  2952. example.</p></li>

  2953. <li><p>As well as for filters, this technique can also be used to configure custom

  2954. handlers and formatters. See <a class="reference internal" href="../library/logging.config.html#logging-config-dict-userdef"><span class="std std-ref">User-defined objects</span></a> for more

  2955. information on how logging supports using user-defined objects in its

  2956. configuration, and see the other cookbook recipe <a class="reference internal" href="#custom-handlers"><span class="std std-ref">Customizing handlers with dictConfig()</span></a> above.</p></li>

  2957. </ul>

  2958. </section>

  2959. <section id="customized-exception-formatting">

  2960. <span id="custom-format-exception"></span><h2>Customized exception formatting<a class="headerlink" href="#customized-exception-formatting" title="Link to this heading">¶</a></h2>

  2961. <p>There might be times when you want to do customized exception formatting - for

  2962. argument’s sake, let’s say you want exactly one line per logged event, even

  2963. when exception information is present. You can do this with a custom formatter

  2964. class, as shown in the following example:</p>

  2965. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  2966. 

  2967. <span class="k">class</span> <span class="nc">OneLineExceptionFormatter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">):</span>

  2968.     <span class="k">def</span> <span class="nf">formatException</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">exc_info</span><span class="p">):</span>

  2969. <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>

  2970. <span class="sd">        Format an exception so that it prints on a single line.</span>

  2971. <span class="sd">        &quot;&quot;&quot;</span>

  2972.         <span class="n">result</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">formatException</span><span class="p">(</span><span class="n">exc_info</span><span class="p">)</span>

  2973.         <span class="k">return</span> <span class="nb">repr</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>  <span class="c1"># or format into one line however you want to</span>

  2974. 

  2975.     <span class="k">def</span> <span class="nf">format</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  2976.         <span class="n">s</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  2977.         <span class="k">if</span> <span class="n">record</span><span class="o">.</span><span class="n">exc_text</span><span class="p">:</span>

  2978.             <span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">+</span> <span class="s1">&#39;|&#39;</span>

  2979.         <span class="k">return</span> <span class="n">s</span>

  2980. 

  2981. <span class="k">def</span> <span class="nf">configure_logging</span><span class="p">():</span>

  2982.     <span class="n">fh</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">FileHandler</span><span class="p">(</span><span class="s1">&#39;output.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span>

  2983.     <span class="n">f</span> <span class="o">=</span> <span class="n">OneLineExceptionFormatter</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1">|</span><span class="si">%(levelname)s</span><span class="s1">|</span><span class="si">%(message)s</span><span class="s1">|&#39;</span><span class="p">,</span>

  2984.                                   <span class="s1">&#39;</span><span class="si">%d</span><span class="s1">/%m/%Y %H:%M:%S&#39;</span><span class="p">)</span>

  2985.     <span class="n">fh</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  2986.     <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  2987.     <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  2988.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">fh</span><span class="p">)</span>

  2989. 

  2990. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  2991.     <span class="n">configure_logging</span><span class="p">()</span>

  2992.     <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Sample message&#39;</span><span class="p">)</span>

  2993.     <span class="k">try</span><span class="p">:</span>

  2994.         <span class="n">x</span> <span class="o">=</span> <span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span>

  2995.     <span class="k">except</span> <span class="ne">ZeroDivisionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>

  2996.         <span class="n">logging</span><span class="o">.</span><span class="n">exception</span><span class="p">(</span><span class="s1">&#39;ZeroDivisionError: </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">e</span><span class="p">)</span>

  2997. 

  2998. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  2999.     <span class="n">main</span><span class="p">()</span>

  3000. </pre></div>

  3001. </div>

  3002. <p>When run, this produces a file with exactly two lines:</p>

  3003. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>28/01/2015 07:21:23|INFO|Sample message|

  3004. 28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|&#39;Traceback (most recent call last):\n  File &quot;logtest7.py&quot;, line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero&#39;|

  3005. </pre></div>

  3006. </div>

  3007. <p>While the above treatment is simplistic, it points the way to how exception

  3008. information can be formatted to your liking. The <a class="reference internal" href="../library/traceback.html#module-traceback" title="traceback: Print or retrieve a stack traceback."><code class="xref py py-mod docutils literal notranslate"><span class="pre">traceback</span></code></a> module may be

  3009. helpful for more specialized needs.</p>

  3010. </section>

  3011. <section id="speaking-logging-messages">

  3012. <span id="spoken-messages"></span><h2>Speaking logging messages<a class="headerlink" href="#speaking-logging-messages" title="Link to this heading">¶</a></h2>

  3013. <p>There might be situations when it is desirable to have logging messages rendered

  3014. in an audible rather than a visible format. This is easy to do if you have

  3015. text-to-speech (TTS) functionality available in your system, even if it doesn’t have

  3016. a Python binding. Most TTS systems have a command line program you can run, and

  3017. this can be invoked from a handler using <a class="reference internal" href="../library/subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a>. It’s assumed here

  3018. that TTS command line programs won’t expect to interact with users or take a

  3019. long time to complete, and that the frequency of logged messages will be not so

  3020. high as to swamp the user with messages, and that it’s acceptable to have the

  3021. messages spoken one at a time rather than concurrently, The example implementation

  3022. below waits for one message to be spoken before the next is processed, and this

  3023. might cause other handlers to be kept waiting. Here is a short example showing

  3024. the approach, which assumes that the <code class="docutils literal notranslate"><span class="pre">espeak</span></code> TTS package is available:</p>

  3025. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3026. <span class="kn">import</span> <span class="nn">subprocess</span>

  3027. <span class="kn">import</span> <span class="nn">sys</span>

  3028. 

  3029. <span class="k">class</span> <span class="nc">TTSHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Handler</span><span class="p">):</span>

  3030.     <span class="k">def</span> <span class="nf">emit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  3031.         <span class="n">msg</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  3032.         <span class="c1"># Speak slowly in a female English voice</span>

  3033.         <span class="n">cmd</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;espeak&#39;</span><span class="p">,</span> <span class="s1">&#39;-s150&#39;</span><span class="p">,</span> <span class="s1">&#39;-ven+f3&#39;</span><span class="p">,</span> <span class="n">msg</span><span class="p">]</span>

  3034.         <span class="n">p</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">Popen</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">stdout</span><span class="o">=</span><span class="n">subprocess</span><span class="o">.</span><span class="n">PIPE</span><span class="p">,</span>

  3035.                              <span class="n">stderr</span><span class="o">=</span><span class="n">subprocess</span><span class="o">.</span><span class="n">STDOUT</span><span class="p">)</span>

  3036.         <span class="c1"># wait for the program to finish</span>

  3037.         <span class="n">p</span><span class="o">.</span><span class="n">communicate</span><span class="p">()</span>

  3038. 

  3039. <span class="k">def</span> <span class="nf">configure_logging</span><span class="p">():</span>

  3040.     <span class="n">h</span> <span class="o">=</span> <span class="n">TTSHandler</span><span class="p">()</span>

  3041.     <span class="n">root</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  3042.     <span class="n">root</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  3043.     <span class="c1"># the default formatter just returns the message</span>

  3044.     <span class="n">root</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3045. 

  3046. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  3047.     <span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Hello&#39;</span><span class="p">)</span>

  3048.     <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Goodbye&#39;</span><span class="p">)</span>

  3049. 

  3050. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3051.     <span class="n">configure_logging</span><span class="p">()</span>

  3052.     <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  3053. </pre></div>

  3054. </div>

  3055. <p>When run, this script should say “Hello” and then “Goodbye” in a female voice.</p>

  3056. <p>The above approach can, of course, be adapted to other TTS systems and even

  3057. other systems altogether which can process messages via external programs run

  3058. from a command line.</p>

  3059. </section>

  3060. <section id="buffering-logging-messages-and-outputting-them-conditionally">

  3061. <span id="buffered-logging"></span><h2>Buffering logging messages and outputting them conditionally<a class="headerlink" href="#buffering-logging-messages-and-outputting-them-conditionally" title="Link to this heading">¶</a></h2>

  3062. <p>There might be situations where you want to log messages in a temporary area

  3063. and only output them if a certain condition occurs. For example, you may want to

  3064. start logging debug events in a function, and if the function completes without

  3065. errors, you don’t want to clutter the log with the collected debug information,

  3066. but if there is an error, you want all the debug information to be output as well

  3067. as the error.</p>

  3068. <p>Here is an example which shows how you could do this using a decorator for your

  3069. functions where you want logging to behave this way. It makes use of the

  3070. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.MemoryHandler" title="logging.handlers.MemoryHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.handlers.MemoryHandler</span></code></a>, which allows buffering of logged events

  3071. until some condition occurs, at which point the buffered events are <code class="docutils literal notranslate"><span class="pre">flushed</span></code>

  3072. - passed to another handler (the <code class="docutils literal notranslate"><span class="pre">target</span></code> handler) for processing. By default,

  3073. the <code class="docutils literal notranslate"><span class="pre">MemoryHandler</span></code> flushed when its buffer gets filled up or an event whose

  3074. level is greater than or equal to a specified threshold is seen. You can use this

  3075. recipe with a more specialised subclass of <code class="docutils literal notranslate"><span class="pre">MemoryHandler</span></code> if you want custom

  3076. flushing behavior.</p>

  3077. <p>The example script has a simple function, <code class="docutils literal notranslate"><span class="pre">foo</span></code>, which just cycles through

  3078. all the logging levels, writing to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> to say what level it’s about

  3079. to log at, and then actually logging a message at that level. You can pass a

  3080. parameter to <code class="docutils literal notranslate"><span class="pre">foo</span></code> which, if true, will log at ERROR and CRITICAL levels -

  3081. otherwise, it only logs at DEBUG, INFO and WARNING levels.</p>

  3082. <p>The script just arranges to decorate <code class="docutils literal notranslate"><span class="pre">foo</span></code> with a decorator which will do the

  3083. conditional logging that’s required. The decorator takes a logger as a parameter

  3084. and attaches a memory handler for the duration of the call to the decorated

  3085. function. The decorator can be additionally parameterised using a target handler,

  3086. a level at which flushing should occur, and a capacity for the buffer (number of

  3087. records buffered). These default to a <a class="reference internal" href="../library/logging.handlers.html#logging.StreamHandler" title="logging.StreamHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamHandler</span></code></a> which

  3088. writes to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>, <code class="docutils literal notranslate"><span class="pre">logging.ERROR</span></code> and <code class="docutils literal notranslate"><span class="pre">100</span></code> respectively.</p>

  3089. <p>Here’s the script:</p>

  3090. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3091. <span class="kn">from</span> <span class="nn">logging.handlers</span> <span class="kn">import</span> <span class="n">MemoryHandler</span>

  3092. <span class="kn">import</span> <span class="nn">sys</span>

  3093. 

  3094. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  3095. <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">NullHandler</span><span class="p">())</span>

  3096. 

  3097. <span class="k">def</span> <span class="nf">log_if_errors</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">target_handler</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">flush_level</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">capacity</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  3098.     <span class="k">if</span> <span class="n">target_handler</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  3099.         <span class="n">target_handler</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">()</span>

  3100.     <span class="k">if</span> <span class="n">flush_level</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  3101.         <span class="n">flush_level</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span>

  3102.     <span class="k">if</span> <span class="n">capacity</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  3103.         <span class="n">capacity</span> <span class="o">=</span> <span class="mi">100</span>

  3104.     <span class="n">handler</span> <span class="o">=</span> <span class="n">MemoryHandler</span><span class="p">(</span><span class="n">capacity</span><span class="p">,</span> <span class="n">flushLevel</span><span class="o">=</span><span class="n">flush_level</span><span class="p">,</span> <span class="n">target</span><span class="o">=</span><span class="n">target_handler</span><span class="p">)</span>

  3105. 

  3106.     <span class="k">def</span> <span class="nf">decorator</span><span class="p">(</span><span class="n">fn</span><span class="p">):</span>

  3107.         <span class="k">def</span> <span class="nf">wrapper</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  3108.             <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  3109.             <span class="k">try</span><span class="p">:</span>

  3110.                 <span class="k">return</span> <span class="n">fn</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  3111.             <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>

  3112.                 <span class="n">logger</span><span class="o">.</span><span class="n">exception</span><span class="p">(</span><span class="s1">&#39;call failed&#39;</span><span class="p">)</span>

  3113.                 <span class="k">raise</span>

  3114.             <span class="k">finally</span><span class="p">:</span>

  3115.                 <span class="nb">super</span><span class="p">(</span><span class="n">MemoryHandler</span><span class="p">,</span> <span class="n">handler</span><span class="p">)</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>

  3116.                 <span class="n">logger</span><span class="o">.</span><span class="n">removeHandler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>

  3117.         <span class="k">return</span> <span class="n">wrapper</span>

  3118. 

  3119.     <span class="k">return</span> <span class="n">decorator</span>

  3120. 

  3121. <span class="k">def</span> <span class="nf">write_line</span><span class="p">(</span><span class="n">s</span><span class="p">):</span>

  3122.     <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;</span><span class="si">%s</span><span class="se">\n</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">s</span><span class="p">)</span>

  3123. 

  3124. <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">fail</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>

  3125.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;about to log at DEBUG ...&#39;</span><span class="p">)</span>

  3126.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Actually logged at DEBUG&#39;</span><span class="p">)</span>

  3127.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;about to log at INFO ...&#39;</span><span class="p">)</span>

  3128.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Actually logged at INFO&#39;</span><span class="p">)</span>

  3129.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;about to log at WARNING ...&#39;</span><span class="p">)</span>

  3130.     <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;Actually logged at WARNING&#39;</span><span class="p">)</span>

  3131.     <span class="k">if</span> <span class="n">fail</span><span class="p">:</span>

  3132.         <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;about to log at ERROR ...&#39;</span><span class="p">)</span>

  3133.         <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">&#39;Actually logged at ERROR&#39;</span><span class="p">)</span>

  3134.         <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;about to log at CRITICAL ...&#39;</span><span class="p">)</span>

  3135.         <span class="n">logger</span><span class="o">.</span><span class="n">critical</span><span class="p">(</span><span class="s1">&#39;Actually logged at CRITICAL&#39;</span><span class="p">)</span>

  3136.     <span class="k">return</span> <span class="n">fail</span>

  3137. 

  3138. <span class="n">decorated_foo</span> <span class="o">=</span> <span class="n">log_if_errors</span><span class="p">(</span><span class="n">logger</span><span class="p">)(</span><span class="n">foo</span><span class="p">)</span>

  3139. 

  3140. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3141.     <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3142.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Calling undecorated foo with False&#39;</span><span class="p">)</span>

  3143.     <span class="k">assert</span> <span class="ow">not</span> <span class="n">foo</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span>

  3144.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Calling undecorated foo with True&#39;</span><span class="p">)</span>

  3145.     <span class="k">assert</span> <span class="n">foo</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span>

  3146.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Calling decorated foo with False&#39;</span><span class="p">)</span>

  3147.     <span class="k">assert</span> <span class="ow">not</span> <span class="n">decorated_foo</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span>

  3148.     <span class="n">write_line</span><span class="p">(</span><span class="s1">&#39;Calling decorated foo with True&#39;</span><span class="p">)</span>

  3149.     <span class="k">assert</span> <span class="n">decorated_foo</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span>

  3150. </pre></div>

  3151. </div>

  3152. <p>When this script is run, the following output should be observed:</p>

  3153. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Calling undecorated foo with False

  3154. about to log at DEBUG ...

  3155. about to log at INFO ...

  3156. about to log at WARNING ...

  3157. Calling undecorated foo with True

  3158. about to log at DEBUG ...

  3159. about to log at INFO ...

  3160. about to log at WARNING ...

  3161. about to log at ERROR ...

  3162. about to log at CRITICAL ...

  3163. Calling decorated foo with False

  3164. about to log at DEBUG ...

  3165. about to log at INFO ...

  3166. about to log at WARNING ...

  3167. Calling decorated foo with True

  3168. about to log at DEBUG ...

  3169. about to log at INFO ...

  3170. about to log at WARNING ...

  3171. about to log at ERROR ...

  3172. Actually logged at DEBUG

  3173. Actually logged at INFO

  3174. Actually logged at WARNING

  3175. Actually logged at ERROR

  3176. about to log at CRITICAL ...

  3177. Actually logged at CRITICAL

  3178. </pre></div>

  3179. </div>

  3180. <p>As you can see, actual logging output only occurs when an event is logged whose

  3181. severity is ERROR or greater, but in that case, any previous events at lower

  3182. severities are also logged.</p>

  3183. <p>You can of course use the conventional means of decoration:</p>

  3184. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@log_if_errors</span><span class="p">(</span><span class="n">logger</span><span class="p">)</span>

  3185. <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">fail</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>

  3186.     <span class="o">...</span>

  3187. </pre></div>

  3188. </div>

  3189. </section>

  3190. <section id="sending-logging-messages-to-email-with-buffering">

  3191. <span id="buffered-smtp"></span><h2>Sending logging messages to email, with buffering<a class="headerlink" href="#sending-logging-messages-to-email-with-buffering" title="Link to this heading">¶</a></h2>

  3192. <p>To illustrate how you can send log messages via email, so that a set number of

  3193. messages are sent per email, you can subclass

  3194. <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.BufferingHandler" title="logging.handlers.BufferingHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferingHandler</span></code></a>. In the following  example, which you can

  3195. adapt to suit your specific needs, a simple test harness is provided which allows you

  3196. to run the script with command line arguments specifying what you typically need to

  3197. send things via SMTP. (Run the downloaded script with the <code class="docutils literal notranslate"><span class="pre">-h</span></code> argument to see the

  3198. required and optional arguments.)</p>

  3199. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3200. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  3201. <span class="kn">import</span> <span class="nn">smtplib</span>

  3202. 

  3203. <span class="k">class</span> <span class="nc">BufferingSMTPHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">BufferingHandler</span><span class="p">):</span>

  3204.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mailhost</span><span class="p">,</span> <span class="n">port</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">,</span> <span class="n">fromaddr</span><span class="p">,</span> <span class="n">toaddrs</span><span class="p">,</span>

  3205.                  <span class="n">subject</span><span class="p">,</span> <span class="n">capacity</span><span class="p">):</span>

  3206.         <span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">BufferingHandler</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">capacity</span><span class="p">)</span>

  3207.         <span class="bp">self</span><span class="o">.</span><span class="n">mailhost</span> <span class="o">=</span> <span class="n">mailhost</span>

  3208.         <span class="bp">self</span><span class="o">.</span><span class="n">mailport</span> <span class="o">=</span> <span class="n">port</span>

  3209.         <span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span>

  3210.         <span class="bp">self</span><span class="o">.</span><span class="n">password</span> <span class="o">=</span> <span class="n">password</span>

  3211.         <span class="bp">self</span><span class="o">.</span><span class="n">fromaddr</span> <span class="o">=</span> <span class="n">fromaddr</span>

  3212.         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">toaddrs</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>

  3213.             <span class="n">toaddrs</span> <span class="o">=</span> <span class="p">[</span><span class="n">toaddrs</span><span class="p">]</span>

  3214.         <span class="bp">self</span><span class="o">.</span><span class="n">toaddrs</span> <span class="o">=</span> <span class="n">toaddrs</span>

  3215.         <span class="bp">self</span><span class="o">.</span><span class="n">subject</span> <span class="o">=</span> <span class="n">subject</span>

  3216.         <span class="bp">self</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">%(asctime)s</span><span class="s2"> </span><span class="si">%(levelname)-5s</span><span class="s2"> </span><span class="si">%(message)s</span><span class="s2">&quot;</span><span class="p">))</span>

  3217. 

  3218.     <span class="k">def</span> <span class="nf">flush</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3219.         <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>

  3220.             <span class="k">try</span><span class="p">:</span>

  3221.                 <span class="n">smtp</span> <span class="o">=</span> <span class="n">smtplib</span><span class="o">.</span><span class="n">SMTP</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">mailhost</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">mailport</span><span class="p">)</span>

  3222.                 <span class="n">smtp</span><span class="o">.</span><span class="n">starttls</span><span class="p">()</span>

  3223.                 <span class="n">smtp</span><span class="o">.</span><span class="n">login</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">username</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">password</span><span class="p">)</span>

  3224.                 <span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;From: </span><span class="si">%s</span><span class="se">\r\n</span><span class="s2">To: </span><span class="si">%s</span><span class="se">\r\n</span><span class="s2">Subject: </span><span class="si">%s</span><span class="se">\r\n\r\n</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fromaddr</span><span class="p">,</span> <span class="s1">&#39;,&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">toaddrs</span><span class="p">),</span> <span class="bp">self</span><span class="o">.</span><span class="n">subject</span><span class="p">)</span>

  3225.                 <span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">:</span>

  3226.                     <span class="n">s</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  3227.                     <span class="n">msg</span> <span class="o">=</span> <span class="n">msg</span> <span class="o">+</span> <span class="n">s</span> <span class="o">+</span> <span class="s2">&quot;</span><span class="se">\r\n</span><span class="s2">&quot;</span>

  3228.                 <span class="n">smtp</span><span class="o">.</span><span class="n">sendmail</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fromaddr</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">toaddrs</span><span class="p">,</span> <span class="n">msg</span><span class="p">)</span>

  3229.                 <span class="n">smtp</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

  3230.             <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>

  3231.                 <span class="k">if</span> <span class="n">logging</span><span class="o">.</span><span class="n">raiseExceptions</span><span class="p">:</span>

  3232.                     <span class="k">raise</span>

  3233.             <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="p">[]</span>

  3234. 

  3235. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3236.     <span class="kn">import</span> <span class="nn">argparse</span>

  3237. 

  3238.     <span class="n">ap</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>

  3239.     <span class="n">aa</span> <span class="o">=</span> <span class="n">ap</span><span class="o">.</span><span class="n">add_argument</span>

  3240.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;host&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;HOST&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;SMTP server&#39;</span><span class="p">)</span>

  3241.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;--port&#39;</span><span class="p">,</span> <span class="s1">&#39;-p&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">587</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;SMTP port&#39;</span><span class="p">)</span>

  3242.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;USER&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;SMTP username&#39;</span><span class="p">)</span>

  3243.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;password&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;PASSWORD&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;SMTP password&#39;</span><span class="p">)</span>

  3244.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;to&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;TO&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Addressee for emails&#39;</span><span class="p">)</span>

  3245.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;sender&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;SENDER&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Sender email address&#39;</span><span class="p">)</span>

  3246.     <span class="n">aa</span><span class="p">(</span><span class="s1">&#39;--subject&#39;</span><span class="p">,</span> <span class="s1">&#39;-s&#39;</span><span class="p">,</span>

  3247.        <span class="n">default</span><span class="o">=</span><span class="s1">&#39;Test Logging email from Python logging module (buffering)&#39;</span><span class="p">,</span>

  3248.        <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Subject of email&#39;</span><span class="p">)</span>

  3249.     <span class="n">options</span> <span class="o">=</span> <span class="n">ap</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>

  3250.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>

  3251.     <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3252.     <span class="n">h</span> <span class="o">=</span> <span class="n">BufferingSMTPHandler</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">host</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">port</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">user</span><span class="p">,</span>

  3253.                              <span class="n">options</span><span class="o">.</span><span class="n">password</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">sender</span><span class="p">,</span>

  3254.                              <span class="n">options</span><span class="o">.</span><span class="n">to</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">subject</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>

  3255.     <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  3256.     <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">102</span><span class="p">):</span>

  3257.         <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;Info index = </span><span class="si">%d</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>

  3258.     <span class="n">h</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>

  3259.     <span class="n">h</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  3260. </pre></div>

  3261. </div>

  3262. <p>If you run this script and your SMTP server is correctly set up, you should find that

  3263. it sends eleven emails to the addressee you specify. The first ten emails will each

  3264. have ten log messages, and the eleventh will have two messages. That makes up 102

  3265. messages as specified in the script.</p>

  3266. </section>

  3267. <section id="formatting-times-using-utc-gmt-via-configuration">

  3268. <span id="utc-formatting"></span><h2>Formatting times using UTC (GMT) via configuration<a class="headerlink" href="#formatting-times-using-utc-gmt-via-configuration" title="Link to this heading">¶</a></h2>

  3269. <p>Sometimes you want to format times using UTC, which can be done using a class

  3270. such as <code class="docutils literal notranslate"><span class="pre">UTCFormatter</span></code>, shown below:</p>

  3271. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3272. <span class="kn">import</span> <span class="nn">time</span>

  3273. 

  3274. <span class="k">class</span> <span class="nc">UTCFormatter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">):</span>

  3275.     <span class="n">converter</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">gmtime</span>

  3276. </pre></div>

  3277. </div>

  3278. <p>and you can then use the <code class="docutils literal notranslate"><span class="pre">UTCFormatter</span></code> in your code instead of

  3279. <a class="reference internal" href="../library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a>. If you want to do that via configuration, you can

  3280. use the <a class="reference internal" href="../library/logging.config.html#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> API with an approach illustrated by

  3281. the following complete example:</p>

  3282. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3283. <span class="kn">import</span> <span class="nn">logging.config</span>

  3284. <span class="kn">import</span> <span class="nn">time</span>

  3285. 

  3286. <span class="k">class</span> <span class="nc">UTCFormatter</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">):</span>

  3287.     <span class="n">converter</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">gmtime</span>

  3288. 

  3289. <span class="n">LOGGING</span> <span class="o">=</span> <span class="p">{</span>

  3290.     <span class="s1">&#39;version&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>

  3291.     <span class="s1">&#39;disable_existing_loggers&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>

  3292.     <span class="s1">&#39;formatters&#39;</span><span class="p">:</span> <span class="p">{</span>

  3293.         <span class="s1">&#39;utc&#39;</span><span class="p">:</span> <span class="p">{</span>

  3294.             <span class="s1">&#39;()&#39;</span><span class="p">:</span> <span class="n">UTCFormatter</span><span class="p">,</span>

  3295.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">,</span>

  3296.         <span class="p">},</span>

  3297.         <span class="s1">&#39;local&#39;</span><span class="p">:</span> <span class="p">{</span>

  3298.             <span class="s1">&#39;format&#39;</span><span class="p">:</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">,</span>

  3299.         <span class="p">}</span>

  3300.     <span class="p">},</span>

  3301.     <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">{</span>

  3302.         <span class="s1">&#39;console1&#39;</span><span class="p">:</span> <span class="p">{</span>

  3303.             <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  3304.             <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;utc&#39;</span><span class="p">,</span>

  3305.         <span class="p">},</span>

  3306.         <span class="s1">&#39;console2&#39;</span><span class="p">:</span> <span class="p">{</span>

  3307.             <span class="s1">&#39;class&#39;</span><span class="p">:</span> <span class="s1">&#39;logging.StreamHandler&#39;</span><span class="p">,</span>

  3308.             <span class="s1">&#39;formatter&#39;</span><span class="p">:</span> <span class="s1">&#39;local&#39;</span><span class="p">,</span>

  3309.         <span class="p">},</span>

  3310.     <span class="p">},</span>

  3311.     <span class="s1">&#39;root&#39;</span><span class="p">:</span> <span class="p">{</span>

  3312.         <span class="s1">&#39;handlers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;console1&#39;</span><span class="p">,</span> <span class="s1">&#39;console2&#39;</span><span class="p">],</span>

  3313.    <span class="p">}</span>

  3314. <span class="p">}</span>

  3315. 

  3316. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3317.     <span class="n">logging</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">dictConfig</span><span class="p">(</span><span class="n">LOGGING</span><span class="p">)</span>

  3318.     <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">&#39;The local time is </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">())</span>

  3319. </pre></div>

  3320. </div>

  3321. <p>When this script is run, it should print something like:</p>

  3322. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015

  3323. 2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015

  3324. </pre></div>

  3325. </div>

  3326. <p>showing how the time is formatted both as local time and UTC, one for each

  3327. handler.</p>

  3328. </section>

  3329. <section id="using-a-context-manager-for-selective-logging">

  3330. <span id="context-manager"></span><h2>Using a context manager for selective logging<a class="headerlink" href="#using-a-context-manager-for-selective-logging" title="Link to this heading">¶</a></h2>

  3331. <p>There are times when it would be useful to temporarily change the logging

  3332. configuration and revert it back after doing something. For this, a context

  3333. manager is the most obvious way of saving and restoring the logging context.

  3334. Here is a simple example of such a context manager, which allows you to

  3335. optionally change the logging level and add a logging handler purely in the

  3336. scope of the context manager:</p>

  3337. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3338. <span class="kn">import</span> <span class="nn">sys</span>

  3339. 

  3340. <span class="k">class</span> <span class="nc">LoggingContext</span><span class="p">:</span>

  3341.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">handler</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">close</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  3342.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logger</span>

  3343.         <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="n">level</span>

  3344.         <span class="bp">self</span><span class="o">.</span><span class="n">handler</span> <span class="o">=</span> <span class="n">handler</span>

  3345.         <span class="bp">self</span><span class="o">.</span><span class="n">close</span> <span class="o">=</span> <span class="n">close</span>

  3346. 

  3347.     <span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3348.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  3349.             <span class="bp">self</span><span class="o">.</span><span class="n">old_level</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">level</span>

  3350.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">level</span><span class="p">)</span>

  3351.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">handler</span><span class="p">:</span>

  3352.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handler</span><span class="p">)</span>

  3353. 

  3354.     <span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">et</span><span class="p">,</span> <span class="n">ev</span><span class="p">,</span> <span class="n">tb</span><span class="p">):</span>

  3355.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>

  3356.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">old_level</span><span class="p">)</span>

  3357.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">handler</span><span class="p">:</span>

  3358.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">removeHandler</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handler</span><span class="p">)</span>

  3359.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">handler</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">close</span><span class="p">:</span>

  3360.             <span class="bp">self</span><span class="o">.</span><span class="n">handler</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  3361.         <span class="c1"># implicit return of None =&gt; don&#39;t swallow exceptions</span>

  3362. </pre></div>

  3363. </div>

  3364. <p>If you specify a level value, the logger’s level is set to that value in the

  3365. scope of the with block covered by the context manager. If you specify a

  3366. handler, it is added to the logger on entry to the block and removed on exit

  3367. from the block. You can also ask the manager to close the handler for you on

  3368. block exit - you could do this if you don’t need the handler any more.</p>

  3369. <p>To illustrate how it works, we can add the following block of code to the

  3370. above:</p>

  3371. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3372.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  3373.     <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">())</span>

  3374.     <span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  3375.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;1. This should appear just once on stderr.&#39;</span><span class="p">)</span>

  3376.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;2. This should not appear.&#39;</span><span class="p">)</span>

  3377.     <span class="k">with</span> <span class="n">LoggingContext</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">):</span>

  3378.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;3. This should appear once on stderr.&#39;</span><span class="p">)</span>

  3379.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;4. This should not appear.&#39;</span><span class="p">)</span>

  3380.     <span class="n">h</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">StreamHandler</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>

  3381.     <span class="k">with</span> <span class="n">LoggingContext</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">handler</span><span class="o">=</span><span class="n">h</span><span class="p">,</span> <span class="n">close</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  3382.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;5. This should appear twice - once on stderr and once on stdout.&#39;</span><span class="p">)</span>

  3383.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;6. This should appear just once on stderr.&#39;</span><span class="p">)</span>

  3384.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;7. This should not appear.&#39;</span><span class="p">)</span>

  3385. </pre></div>

  3386. </div>

  3387. <p>We initially set the logger’s level to <code class="docutils literal notranslate"><span class="pre">INFO</span></code>, so message #1 appears and

  3388. message #2 doesn’t. We then change the level to <code class="docutils literal notranslate"><span class="pre">DEBUG</span></code> temporarily in the

  3389. following <code class="docutils literal notranslate"><span class="pre">with</span></code> block, and so message #3 appears. After the block exits, the

  3390. logger’s level is restored to <code class="docutils literal notranslate"><span class="pre">INFO</span></code> and so message #4 doesn’t appear. In the

  3391. next <code class="docutils literal notranslate"><span class="pre">with</span></code> block, we set the level to <code class="docutils literal notranslate"><span class="pre">DEBUG</span></code> again but also add a handler

  3392. writing to <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>. Thus, message #5 appears twice on the console (once

  3393. via <code class="docutils literal notranslate"><span class="pre">stderr</span></code> and once via <code class="docutils literal notranslate"><span class="pre">stdout</span></code>). After the <code class="docutils literal notranslate"><span class="pre">with</span></code> statement’s

  3394. completion, the status is as it was before so message #6 appears (like message

  3395. #1) whereas message #7 doesn’t (just like message #2).</p>

  3396. <p>If we run the resulting script, the result is as follows:</p>

  3397. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>logctx.py

  3398. <span class="go">1. This should appear just once on stderr.</span>

  3399. <span class="go">3. This should appear once on stderr.</span>

  3400. <span class="go">5. This should appear twice - once on stderr and once on stdout.</span>

  3401. <span class="go">5. This should appear twice - once on stderr and once on stdout.</span>

  3402. <span class="go">6. This should appear just once on stderr.</span>

  3403. </pre></div>

  3404. </div>

  3405. <p>If we run it again, but pipe <code class="docutils literal notranslate"><span class="pre">stderr</span></code> to <code class="docutils literal notranslate"><span class="pre">/dev/null</span></code>, we see the following,

  3406. which is the only message written to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>:</p>

  3407. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>logctx.py<span class="w"> </span><span class="m">2</span>&gt;/dev/null

  3408. <span class="go">5. This should appear twice - once on stderr and once on stdout.</span>

  3409. </pre></div>

  3410. </div>

  3411. <p>Once again, but piping <code class="docutils literal notranslate"><span class="pre">stdout</span></code> to <code class="docutils literal notranslate"><span class="pre">/dev/null</span></code>, we get:</p>

  3412. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>logctx.py<span class="w"> </span>&gt;/dev/null

  3413. <span class="go">1. This should appear just once on stderr.</span>

  3414. <span class="go">3. This should appear once on stderr.</span>

  3415. <span class="go">5. This should appear twice - once on stderr and once on stdout.</span>

  3416. <span class="go">6. This should appear just once on stderr.</span>

  3417. </pre></div>

  3418. </div>

  3419. <p>In this case, the message #5 printed to <code class="docutils literal notranslate"><span class="pre">stdout</span></code> doesn’t appear, as expected.</p>

  3420. <p>Of course, the approach described here can be generalised, for example to attach

  3421. logging filters temporarily. Note that the above code works in Python 2 as well

  3422. as Python 3.</p>

  3423. </section>

  3424. <section id="a-cli-application-starter-template">

  3425. <span id="starter-template"></span><h2>A CLI application starter template<a class="headerlink" href="#a-cli-application-starter-template" title="Link to this heading">¶</a></h2>

  3426. <p>Here’s an example which shows how you can:</p>

  3427. <ul class="simple">

  3428. <li><p>Use a logging level based on command-line arguments</p></li>

  3429. <li><p>Dispatch to multiple subcommands in separate files, all logging at the same

  3430. level in a consistent way</p></li>

  3431. <li><p>Make use of simple, minimal configuration</p></li>

  3432. </ul>

  3433. <p>Suppose we have a command-line application whose job is to stop, start or

  3434. restart some services. This could be organised for the purposes of illustration

  3435. as a file <code class="docutils literal notranslate"><span class="pre">app.py</span></code> that is the main script for the application, with individual

  3436. commands implemented in <code class="docutils literal notranslate"><span class="pre">start.py</span></code>, <code class="docutils literal notranslate"><span class="pre">stop.py</span></code> and <code class="docutils literal notranslate"><span class="pre">restart.py</span></code>. Suppose

  3437. further that we want to control the verbosity of the application via a

  3438. command-line argument, defaulting to <code class="docutils literal notranslate"><span class="pre">logging.INFO</span></code>. Here’s one way that

  3439. <code class="docutils literal notranslate"><span class="pre">app.py</span></code> could be written:</p>

  3440. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>

  3441. <span class="kn">import</span> <span class="nn">importlib</span>

  3442. <span class="kn">import</span> <span class="nn">logging</span>

  3443. <span class="kn">import</span> <span class="nn">os</span>

  3444. <span class="kn">import</span> <span class="nn">sys</span>

  3445. 

  3446. <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

  3447.     <span class="n">scriptname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="vm">__file__</span><span class="p">)</span>

  3448.     <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">scriptname</span><span class="p">)</span>

  3449.     <span class="n">levels</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;DEBUG&#39;</span><span class="p">,</span> <span class="s1">&#39;INFO&#39;</span><span class="p">,</span> <span class="s1">&#39;WARNING&#39;</span><span class="p">,</span> <span class="s1">&#39;ERROR&#39;</span><span class="p">,</span> <span class="s1">&#39;CRITICAL&#39;</span><span class="p">)</span>

  3450.     <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--log-level&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;INFO&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">levels</span><span class="p">)</span>

  3451.     <span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="s1">&#39;command&#39;</span><span class="p">,</span>

  3452.                                        <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Available commands:&#39;</span><span class="p">)</span>

  3453.     <span class="n">start_cmd</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;start&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Start a service&#39;</span><span class="p">)</span>

  3454.     <span class="n">start_cmd</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;name&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;NAME&#39;</span><span class="p">,</span>

  3455.                            <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Name of service to start&#39;</span><span class="p">)</span>

  3456.     <span class="n">stop_cmd</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;stop&#39;</span><span class="p">,</span>

  3457.                                      <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Stop one or more services&#39;</span><span class="p">)</span>

  3458.     <span class="n">stop_cmd</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;names&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;NAME&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span>

  3459.                           <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Name of service to stop&#39;</span><span class="p">)</span>

  3460.     <span class="n">restart_cmd</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;restart&#39;</span><span class="p">,</span>

  3461.                                         <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Restart one or more services&#39;</span><span class="p">)</span>

  3462.     <span class="n">restart_cmd</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;names&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;NAME&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span>

  3463.                              <span class="n">help</span><span class="o">=</span><span class="s1">&#39;Name of service to restart&#39;</span><span class="p">)</span>

  3464.     <span class="n">options</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>

  3465.     <span class="c1"># the code to dispatch commands could all be in this file. For the purposes</span>

  3466.     <span class="c1"># of illustration only, we implement each command in a separate module.</span>

  3467.     <span class="k">try</span><span class="p">:</span>

  3468.         <span class="n">mod</span> <span class="o">=</span> <span class="n">importlib</span><span class="o">.</span><span class="n">import_module</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">command</span><span class="p">)</span>

  3469.         <span class="n">cmd</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">mod</span><span class="p">,</span> <span class="s1">&#39;command&#39;</span><span class="p">)</span>

  3470.     <span class="k">except</span> <span class="p">(</span><span class="ne">ImportError</span><span class="p">,</span> <span class="ne">AttributeError</span><span class="p">):</span>

  3471.         <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Unable to find the code for command </span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">options</span><span class="o">.</span><span class="n">command</span><span class="p">)</span>

  3472.         <span class="k">return</span> <span class="mi">1</span>

  3473.     <span class="c1"># Could get fancy here and load configuration from file or dictionary</span>

  3474.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">log_level</span><span class="p">,</span>

  3475.                         <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(levelname)s</span><span class="s1"> </span><span class="si">%(name)s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span><span class="p">)</span>

  3476.     <span class="n">cmd</span><span class="p">(</span><span class="n">options</span><span class="p">)</span>

  3477. 

  3478. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3479.     <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  3480. </pre></div>

  3481. </div>

  3482. <p>And the <code class="docutils literal notranslate"><span class="pre">start</span></code>, <code class="docutils literal notranslate"><span class="pre">stop</span></code> and <code class="docutils literal notranslate"><span class="pre">restart</span></code> commands can be implemented in

  3483. separate modules, like so for starting:</p>

  3484. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># start.py</span>

  3485. <span class="kn">import</span> <span class="nn">logging</span>

  3486. 

  3487. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  3488. 

  3489. <span class="k">def</span> <span class="nf">command</span><span class="p">(</span><span class="n">options</span><span class="p">):</span>

  3490.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;About to start </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  3491.     <span class="c1"># actually do the command processing here ...</span>

  3492.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Started the </span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1"> service.&#39;</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  3493. </pre></div>

  3494. </div>

  3495. <p>and thus for stopping:</p>

  3496. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># stop.py</span>

  3497. <span class="kn">import</span> <span class="nn">logging</span>

  3498. 

  3499. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  3500. 

  3501. <span class="k">def</span> <span class="nf">command</span><span class="p">(</span><span class="n">options</span><span class="p">):</span>

  3502.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">)</span>

  3503.     <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>

  3504.         <span class="n">plural</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>

  3505.         <span class="n">services</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

  3506.     <span class="k">else</span><span class="p">:</span>

  3507.         <span class="n">plural</span> <span class="o">=</span> <span class="s1">&#39;s&#39;</span>

  3508.         <span class="n">services</span> <span class="o">=</span> <span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">name</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">)</span>

  3509.         <span class="n">i</span> <span class="o">=</span> <span class="n">services</span><span class="o">.</span><span class="n">rfind</span><span class="p">(</span><span class="s1">&#39;, &#39;</span><span class="p">)</span>

  3510.         <span class="n">services</span> <span class="o">=</span> <span class="n">services</span><span class="p">[:</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="s1">&#39; and &#39;</span> <span class="o">+</span> <span class="n">services</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">2</span><span class="p">:]</span>

  3511.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;About to stop </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">services</span><span class="p">)</span>

  3512.     <span class="c1"># actually do the command processing here ...</span>

  3513.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Stopped the </span><span class="si">%s</span><span class="s1"> service</span><span class="si">%s</span><span class="s1">.&#39;</span><span class="p">,</span> <span class="n">services</span><span class="p">,</span> <span class="n">plural</span><span class="p">)</span>

  3514. </pre></div>

  3515. </div>

  3516. <p>and similarly for restarting:</p>

  3517. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># restart.py</span>

  3518. <span class="kn">import</span> <span class="nn">logging</span>

  3519. 

  3520. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  3521. 

  3522. <span class="k">def</span> <span class="nf">command</span><span class="p">(</span><span class="n">options</span><span class="p">):</span>

  3523.     <span class="n">n</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">)</span>

  3524.     <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>

  3525.         <span class="n">plural</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>

  3526.         <span class="n">services</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

  3527.     <span class="k">else</span><span class="p">:</span>

  3528.         <span class="n">plural</span> <span class="o">=</span> <span class="s1">&#39;s&#39;</span>

  3529.         <span class="n">services</span> <span class="o">=</span> <span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\&#39;</span><span class="si">%s</span><span class="se">\&#39;</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">name</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">names</span><span class="p">)</span>

  3530.         <span class="n">i</span> <span class="o">=</span> <span class="n">services</span><span class="o">.</span><span class="n">rfind</span><span class="p">(</span><span class="s1">&#39;, &#39;</span><span class="p">)</span>

  3531.         <span class="n">services</span> <span class="o">=</span> <span class="n">services</span><span class="p">[:</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="s1">&#39; and &#39;</span> <span class="o">+</span> <span class="n">services</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">2</span><span class="p">:]</span>

  3532.     <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;About to restart </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">services</span><span class="p">)</span>

  3533.     <span class="c1"># actually do the command processing here ...</span>

  3534.     <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;Restarted the </span><span class="si">%s</span><span class="s1"> service</span><span class="si">%s</span><span class="s1">.&#39;</span><span class="p">,</span> <span class="n">services</span><span class="p">,</span> <span class="n">plural</span><span class="p">)</span>

  3535. </pre></div>

  3536. </div>

  3537. <p>If we run this application with the default log level, we get output like this:</p>

  3538. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>start<span class="w"> </span>foo

  3539. <span class="go">INFO start Started the &#39;foo&#39; service.</span>

  3540. 

  3541. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>stop<span class="w"> </span>foo<span class="w"> </span>bar

  3542. <span class="go">INFO stop Stopped the &#39;foo&#39; and &#39;bar&#39; services.</span>

  3543. 

  3544. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>restart<span class="w"> </span>foo<span class="w"> </span>bar<span class="w"> </span>baz

  3545. <span class="go">INFO restart Restarted the &#39;foo&#39;, &#39;bar&#39; and &#39;baz&#39; services.</span>

  3546. </pre></div>

  3547. </div>

  3548. <p>The first word is the logging level, and the second word is the module or

  3549. package name of the place where the event was logged.</p>

  3550. <p>If we change the logging level, then we can change the information sent to the

  3551. log. For example, if we want more information:</p>

  3552. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>DEBUG<span class="w"> </span>start<span class="w"> </span>foo

  3553. <span class="go">DEBUG start About to start foo</span>

  3554. <span class="go">INFO start Started the &#39;foo&#39; service.</span>

  3555. 

  3556. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>DEBUG<span class="w"> </span>stop<span class="w"> </span>foo<span class="w"> </span>bar

  3557. <span class="go">DEBUG stop About to stop &#39;foo&#39; and &#39;bar&#39;</span>

  3558. <span class="go">INFO stop Stopped the &#39;foo&#39; and &#39;bar&#39; services.</span>

  3559. 

  3560. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>DEBUG<span class="w"> </span>restart<span class="w"> </span>foo<span class="w"> </span>bar<span class="w"> </span>baz

  3561. <span class="go">DEBUG restart About to restart &#39;foo&#39;, &#39;bar&#39; and &#39;baz&#39;</span>

  3562. <span class="go">INFO restart Restarted the &#39;foo&#39;, &#39;bar&#39; and &#39;baz&#39; services.</span>

  3563. </pre></div>

  3564. </div>

  3565. <p>And if we want less:</p>

  3566. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>WARNING<span class="w"> </span>start<span class="w"> </span>foo

  3567. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>WARNING<span class="w"> </span>stop<span class="w"> </span>foo<span class="w"> </span>bar

  3568. <span class="gp">$ </span>python<span class="w"> </span>app.py<span class="w"> </span>--log-level<span class="w"> </span>WARNING<span class="w"> </span>restart<span class="w"> </span>foo<span class="w"> </span>bar<span class="w"> </span>baz

  3569. </pre></div>

  3570. </div>

  3571. <p>In this case, the commands don’t print anything to the console, since nothing

  3572. at <code class="docutils literal notranslate"><span class="pre">WARNING</span></code> level or above is logged by them.</p>

  3573. </section>

  3574. <section id="a-qt-gui-for-logging">

  3575. <span id="qt-gui"></span><h2>A Qt GUI for logging<a class="headerlink" href="#a-qt-gui-for-logging" title="Link to this heading">¶</a></h2>

  3576. <p>A question that comes up from time to time is about how to log to a GUI

  3577. application. The <a class="reference external" href="https://www.qt.io/">Qt</a> framework is a popular

  3578. cross-platform UI framework with Python bindings using <a class="reference external" href="https://pypi.org/project/PySide2/">PySide2</a> or <a class="reference external" href="https://pypi.org/project/PyQt5/">PyQt5</a> libraries.</p>

  3579. <p>The following example shows how to log to a Qt GUI. This introduces a simple

  3580. <code class="docutils literal notranslate"><span class="pre">QtHandler</span></code> class which takes a callable, which should be a slot in the main

  3581. thread that does GUI updates. A worker thread is also created to show how you

  3582. can log to the GUI from both the UI itself (via a button for manual logging)

  3583. as well as a worker thread doing work in the background (here, just logging

  3584. messages at random levels with random short delays in between).</p>

  3585. <p>The worker thread is implemented using Qt’s <code class="docutils literal notranslate"><span class="pre">QThread</span></code> class rather than the

  3586. <a class="reference internal" href="../library/threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module, as there are circumstances where one has to use

  3587. <code class="docutils literal notranslate"><span class="pre">QThread</span></code>, which offers better integration with other <code class="docutils literal notranslate"><span class="pre">Qt</span></code> components.</p>

  3588. <p>The code should work with recent releases of any of <code class="docutils literal notranslate"><span class="pre">PySide6</span></code>, <code class="docutils literal notranslate"><span class="pre">PyQt6</span></code>,

  3589. <code class="docutils literal notranslate"><span class="pre">PySide2</span></code> or <code class="docutils literal notranslate"><span class="pre">PyQt5</span></code>. You should be able to adapt the approach to earlier

  3590. versions of Qt. Please refer to the comments in the code snippet for more

  3591. detailed information.</p>

  3592. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">datetime</span>

  3593. <span class="kn">import</span> <span class="nn">logging</span>

  3594. <span class="kn">import</span> <span class="nn">random</span>

  3595. <span class="kn">import</span> <span class="nn">sys</span>

  3596. <span class="kn">import</span> <span class="nn">time</span>

  3597. 

  3598. <span class="c1"># Deal with minor differences between different Qt packages</span>

  3599. <span class="k">try</span><span class="p">:</span>

  3600.     <span class="kn">from</span> <span class="nn">PySide6</span> <span class="kn">import</span> <span class="n">QtCore</span><span class="p">,</span> <span class="n">QtGui</span><span class="p">,</span> <span class="n">QtWidgets</span>

  3601.     <span class="n">Signal</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">Signal</span>

  3602.     <span class="n">Slot</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">Slot</span>

  3603. <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>

  3604.     <span class="k">try</span><span class="p">:</span>

  3605.         <span class="kn">from</span> <span class="nn">PyQt6</span> <span class="kn">import</span> <span class="n">QtCore</span><span class="p">,</span> <span class="n">QtGui</span><span class="p">,</span> <span class="n">QtWidgets</span>

  3606.         <span class="n">Signal</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">pyqtSignal</span>

  3607.         <span class="n">Slot</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">pyqtSlot</span>

  3608.     <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>

  3609.         <span class="k">try</span><span class="p">:</span>

  3610.             <span class="kn">from</span> <span class="nn">PySide2</span> <span class="kn">import</span> <span class="n">QtCore</span><span class="p">,</span> <span class="n">QtGui</span><span class="p">,</span> <span class="n">QtWidgets</span>

  3611.             <span class="n">Signal</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">Signal</span>

  3612.             <span class="n">Slot</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">Slot</span>

  3613.         <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>

  3614.             <span class="kn">from</span> <span class="nn">PyQt5</span> <span class="kn">import</span> <span class="n">QtCore</span><span class="p">,</span> <span class="n">QtGui</span><span class="p">,</span> <span class="n">QtWidgets</span>

  3615.             <span class="n">Signal</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">pyqtSignal</span>

  3616.             <span class="n">Slot</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">pyqtSlot</span>

  3617. 

  3618. <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>

  3619. 

  3620. 

  3621. <span class="c1">#</span>

  3622. <span class="c1"># Signals need to be contained in a QObject or subclass in order to be correctly</span>

  3623. <span class="c1"># initialized.</span>

  3624. <span class="c1">#</span>

  3625. <span class="k">class</span> <span class="nc">Signaller</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="p">):</span>

  3626.     <span class="n">signal</span> <span class="o">=</span> <span class="n">Signal</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">LogRecord</span><span class="p">)</span>

  3627. 

  3628. <span class="c1">#</span>

  3629. <span class="c1"># Output to a Qt GUI is only supposed to happen on the main thread. So, this</span>

  3630. <span class="c1"># handler is designed to take a slot function which is set up to run in the main</span>

  3631. <span class="c1"># thread. In this example, the function takes a string argument which is a</span>

  3632. <span class="c1"># formatted log message, and the log record which generated it. The formatted</span>

  3633. <span class="c1"># string is just a convenience - you could format a string for output any way</span>

  3634. <span class="c1"># you like in the slot function itself.</span>

  3635. <span class="c1">#</span>

  3636. <span class="c1"># You specify the slot function to do whatever GUI updates you want. The handler</span>

  3637. <span class="c1"># doesn&#39;t know or care about specific UI elements.</span>

  3638. <span class="c1">#</span>

  3639. <span class="k">class</span> <span class="nc">QtHandler</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">Handler</span><span class="p">):</span>

  3640.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">slotfunc</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  3641.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  3642.         <span class="bp">self</span><span class="o">.</span><span class="n">signaller</span> <span class="o">=</span> <span class="n">Signaller</span><span class="p">()</span>

  3643.         <span class="bp">self</span><span class="o">.</span><span class="n">signaller</span><span class="o">.</span><span class="n">signal</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">slotfunc</span><span class="p">)</span>

  3644. 

  3645.     <span class="k">def</span> <span class="nf">emit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  3646.         <span class="n">s</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  3647.         <span class="bp">self</span><span class="o">.</span><span class="n">signaller</span><span class="o">.</span><span class="n">signal</span><span class="o">.</span><span class="n">emit</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">record</span><span class="p">)</span>

  3648. 

  3649. <span class="c1">#</span>

  3650. <span class="c1"># This example uses QThreads, which means that the threads at the Python level</span>

  3651. <span class="c1"># are named something like &quot;Dummy-1&quot;. The function below gets the Qt name of the</span>

  3652. <span class="c1"># current thread.</span>

  3653. <span class="c1">#</span>

  3654. <span class="k">def</span> <span class="nf">ctname</span><span class="p">():</span>

  3655.     <span class="k">return</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">QThread</span><span class="o">.</span><span class="n">currentThread</span><span class="p">()</span><span class="o">.</span><span class="n">objectName</span><span class="p">()</span>

  3656. 

  3657. 

  3658. <span class="c1">#</span>

  3659. <span class="c1"># Used to generate random levels for logging.</span>

  3660. <span class="c1">#</span>

  3661. <span class="n">LEVELS</span> <span class="o">=</span> <span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">,</span>

  3662.           <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">)</span>

  3663. 

  3664. <span class="c1">#</span>

  3665. <span class="c1"># This worker class represents work that is done in a thread separate to the</span>

  3666. <span class="c1"># main thread. The way the thread is kicked off to do work is via a button press</span>

  3667. <span class="c1"># that connects to a slot in the worker.</span>

  3668. <span class="c1">#</span>

  3669. <span class="c1"># Because the default threadName value in the LogRecord isn&#39;t much use, we add</span>

  3670. <span class="c1"># a qThreadName which contains the QThread name as computed above, and pass that</span>

  3671. <span class="c1"># value in an &quot;extra&quot; dictionary which is used to update the LogRecord with the</span>

  3672. <span class="c1"># QThread name.</span>

  3673. <span class="c1">#</span>

  3674. <span class="c1"># This example worker just outputs messages sequentially, interspersed with</span>

  3675. <span class="c1"># random delays of the order of a few seconds.</span>

  3676. <span class="c1">#</span>

  3677. <span class="k">class</span> <span class="nc">Worker</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="p">):</span>

  3678.     <span class="nd">@Slot</span><span class="p">()</span>

  3679.     <span class="k">def</span> <span class="nf">start</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3680.         <span class="n">extra</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;qThreadName&#39;</span><span class="p">:</span> <span class="n">ctname</span><span class="p">()</span> <span class="p">}</span>

  3681.         <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Started work&#39;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">extra</span><span class="p">)</span>

  3682.         <span class="n">i</span> <span class="o">=</span> <span class="mi">1</span>

  3683.         <span class="c1"># Let the thread run until interrupted. This allows reasonably clean</span>

  3684.         <span class="c1"># thread termination.</span>

  3685.         <span class="k">while</span> <span class="ow">not</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">QThread</span><span class="o">.</span><span class="n">currentThread</span><span class="p">()</span><span class="o">.</span><span class="n">isInterruptionRequested</span><span class="p">():</span>

  3686.             <span class="n">delay</span> <span class="o">=</span> <span class="mf">0.5</span> <span class="o">+</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span> <span class="o">*</span> <span class="mi">2</span>

  3687.             <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="n">delay</span><span class="p">)</span>

  3688.             <span class="k">try</span><span class="p">:</span>

  3689.                 <span class="k">if</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span> <span class="o">&lt;</span> <span class="mf">0.1</span><span class="p">:</span>

  3690.                     <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;Exception raised: </span><span class="si">%d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">i</span><span class="p">)</span>

  3691.                 <span class="k">else</span><span class="p">:</span>

  3692.                     <span class="n">level</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">LEVELS</span><span class="p">)</span>

  3693.                     <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="s1">&#39;Message after delay of </span><span class="si">%3.1f</span><span class="s1">: </span><span class="si">%d</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">delay</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">extra</span><span class="p">)</span>

  3694.             <span class="k">except</span> <span class="ne">ValueError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>

  3695.                 <span class="n">logger</span><span class="o">.</span><span class="n">exception</span><span class="p">(</span><span class="s1">&#39;Failed: </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">extra</span><span class="p">)</span>

  3696.             <span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>

  3697. 

  3698. <span class="c1">#</span>

  3699. <span class="c1"># Implement a simple UI for this cookbook example. This contains:</span>

  3700. <span class="c1">#</span>

  3701. <span class="c1"># * A read-only text edit window which holds formatted log messages</span>

  3702. <span class="c1"># * A button to start work and log stuff in a separate thread</span>

  3703. <span class="c1"># * A button to log something from the main thread</span>

  3704. <span class="c1"># * A button to clear the log window</span>

  3705. <span class="c1">#</span>

  3706. <span class="k">class</span> <span class="nc">Window</span><span class="p">(</span><span class="n">QtWidgets</span><span class="o">.</span><span class="n">QWidget</span><span class="p">):</span>

  3707. 

  3708.     <span class="n">COLORS</span> <span class="o">=</span> <span class="p">{</span>

  3709.         <span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">:</span> <span class="s1">&#39;black&#39;</span><span class="p">,</span>

  3710.         <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">:</span> <span class="s1">&#39;blue&#39;</span><span class="p">,</span>

  3711.         <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">:</span> <span class="s1">&#39;orange&#39;</span><span class="p">,</span>

  3712.         <span class="n">logging</span><span class="o">.</span><span class="n">ERROR</span><span class="p">:</span> <span class="s1">&#39;red&#39;</span><span class="p">,</span>

  3713.         <span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">:</span> <span class="s1">&#39;purple&#39;</span><span class="p">,</span>

  3714.     <span class="p">}</span>

  3715. 

  3716.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">app</span><span class="p">):</span>

  3717.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>

  3718.         <span class="bp">self</span><span class="o">.</span><span class="n">app</span> <span class="o">=</span> <span class="n">app</span>

  3719.         <span class="bp">self</span><span class="o">.</span><span class="n">textedit</span> <span class="o">=</span> <span class="n">te</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QPlainTextEdit</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

  3720.         <span class="c1"># Set whatever the default monospace font is for the platform</span>

  3721.         <span class="n">f</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QFont</span><span class="p">(</span><span class="s1">&#39;nosuchfont&#39;</span><span class="p">)</span>

  3722.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s1">&#39;Monospace&#39;</span><span class="p">):</span>

  3723.             <span class="n">f</span><span class="o">.</span><span class="n">setStyleHint</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">Monospace</span><span class="p">)</span>

  3724.         <span class="k">else</span><span class="p">:</span>

  3725.             <span class="n">f</span><span class="o">.</span><span class="n">setStyleHint</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">StyleHint</span><span class="o">.</span><span class="n">Monospace</span><span class="p">)</span>  <span class="c1"># for Qt6</span>

  3726.         <span class="n">te</span><span class="o">.</span><span class="n">setFont</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>

  3727.         <span class="n">te</span><span class="o">.</span><span class="n">setReadOnly</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span>

  3728.         <span class="n">PB</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QPushButton</span>

  3729.         <span class="bp">self</span><span class="o">.</span><span class="n">work_button</span> <span class="o">=</span> <span class="n">PB</span><span class="p">(</span><span class="s1">&#39;Start background work&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>

  3730.         <span class="bp">self</span><span class="o">.</span><span class="n">log_button</span> <span class="o">=</span> <span class="n">PB</span><span class="p">(</span><span class="s1">&#39;Log a message at a random level&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>

  3731.         <span class="bp">self</span><span class="o">.</span><span class="n">clear_button</span> <span class="o">=</span> <span class="n">PB</span><span class="p">(</span><span class="s1">&#39;Clear log window&#39;</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>

  3732.         <span class="bp">self</span><span class="o">.</span><span class="n">handler</span> <span class="o">=</span> <span class="n">h</span> <span class="o">=</span> <span class="n">QtHandler</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">update_status</span><span class="p">)</span>

  3733.         <span class="c1"># Remember to use qThreadName rather than threadName in the format string.</span>

  3734.         <span class="n">fs</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(qThreadName)-12s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">&#39;</span>

  3735.         <span class="n">formatter</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">Formatter</span><span class="p">(</span><span class="n">fs</span><span class="p">)</span>

  3736.         <span class="n">h</span><span class="o">.</span><span class="n">setFormatter</span><span class="p">(</span><span class="n">formatter</span><span class="p">)</span>

  3737.         <span class="n">logger</span><span class="o">.</span><span class="n">addHandler</span><span class="p">(</span><span class="n">h</span><span class="p">)</span>

  3738.         <span class="c1"># Set up to terminate the QThread when we exit</span>

  3739.         <span class="n">app</span><span class="o">.</span><span class="n">aboutToQuit</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">force_quit</span><span class="p">)</span>

  3740. 

  3741.         <span class="c1"># Lay out all the widgets</span>

  3742.         <span class="n">layout</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QVBoxLayout</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

  3743.         <span class="n">layout</span><span class="o">.</span><span class="n">addWidget</span><span class="p">(</span><span class="n">te</span><span class="p">)</span>

  3744.         <span class="n">layout</span><span class="o">.</span><span class="n">addWidget</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">work_button</span><span class="p">)</span>

  3745.         <span class="n">layout</span><span class="o">.</span><span class="n">addWidget</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">log_button</span><span class="p">)</span>

  3746.         <span class="n">layout</span><span class="o">.</span><span class="n">addWidget</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">clear_button</span><span class="p">)</span>

  3747.         <span class="bp">self</span><span class="o">.</span><span class="n">setFixedSize</span><span class="p">(</span><span class="mi">900</span><span class="p">,</span> <span class="mi">400</span><span class="p">)</span>

  3748. 

  3749.         <span class="c1"># Connect the non-worker slots and signals</span>

  3750.         <span class="bp">self</span><span class="o">.</span><span class="n">log_button</span><span class="o">.</span><span class="n">clicked</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">manual_update</span><span class="p">)</span>

  3751.         <span class="bp">self</span><span class="o">.</span><span class="n">clear_button</span><span class="o">.</span><span class="n">clicked</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">clear_display</span><span class="p">)</span>

  3752. 

  3753.         <span class="c1"># Start a new worker thread and connect the slots for the worker</span>

  3754.         <span class="bp">self</span><span class="o">.</span><span class="n">start_thread</span><span class="p">()</span>

  3755.         <span class="bp">self</span><span class="o">.</span><span class="n">work_button</span><span class="o">.</span><span class="n">clicked</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">worker</span><span class="o">.</span><span class="n">start</span><span class="p">)</span>

  3756.         <span class="c1"># Once started, the button should be disabled</span>

  3757.         <span class="bp">self</span><span class="o">.</span><span class="n">work_button</span><span class="o">.</span><span class="n">clicked</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="k">lambda</span> <span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">work_button</span><span class="o">.</span><span class="n">setEnabled</span><span class="p">(</span><span class="kc">False</span><span class="p">))</span>

  3758. 

  3759.     <span class="k">def</span> <span class="nf">start_thread</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3760.         <span class="bp">self</span><span class="o">.</span><span class="n">worker</span> <span class="o">=</span> <span class="n">Worker</span><span class="p">()</span>

  3761.         <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span> <span class="o">=</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">QThread</span><span class="p">()</span>

  3762.         <span class="bp">self</span><span class="o">.</span><span class="n">worker</span><span class="o">.</span><span class="n">setObjectName</span><span class="p">(</span><span class="s1">&#39;Worker&#39;</span><span class="p">)</span>

  3763.         <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">setObjectName</span><span class="p">(</span><span class="s1">&#39;WorkerThread&#39;</span><span class="p">)</span>  <span class="c1"># for qThreadName</span>

  3764.         <span class="bp">self</span><span class="o">.</span><span class="n">worker</span><span class="o">.</span><span class="n">moveToThread</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="p">)</span>

  3765.         <span class="c1"># This will start an event loop in the worker thread</span>

  3766.         <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  3767. 

  3768.     <span class="k">def</span> <span class="nf">kill_thread</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3769.         <span class="c1"># Just tell the worker to stop, then tell it to quit and wait for that</span>

  3770.         <span class="c1"># to happen</span>

  3771.         <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">requestInterruption</span><span class="p">()</span>

  3772.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">isRunning</span><span class="p">():</span>

  3773.             <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

  3774.             <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>

  3775.         <span class="k">else</span><span class="p">:</span>

  3776.             <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;worker has already exited.&#39;</span><span class="p">)</span>

  3777. 

  3778.     <span class="k">def</span> <span class="nf">force_quit</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3779.         <span class="c1"># For use when the window is closed</span>

  3780.         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">worker_thread</span><span class="o">.</span><span class="n">isRunning</span><span class="p">():</span>

  3781.             <span class="bp">self</span><span class="o">.</span><span class="n">kill_thread</span><span class="p">()</span>

  3782. 

  3783.     <span class="c1"># The functions below update the UI and run in the main thread because</span>

  3784.     <span class="c1"># that&#39;s where the slots are set up</span>

  3785. 

  3786.     <span class="nd">@Slot</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">LogRecord</span><span class="p">)</span>

  3787.     <span class="k">def</span> <span class="nf">update_status</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">status</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  3788.         <span class="n">color</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">COLORS</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">levelno</span><span class="p">,</span> <span class="s1">&#39;black&#39;</span><span class="p">)</span>

  3789.         <span class="n">s</span> <span class="o">=</span> <span class="s1">&#39;&lt;pre&gt;&lt;font color=&quot;</span><span class="si">%s</span><span class="s1">&quot;&gt;</span><span class="si">%s</span><span class="s1">&lt;/font&gt;&lt;/pre&gt;&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">color</span><span class="p">,</span> <span class="n">status</span><span class="p">)</span>

  3790.         <span class="bp">self</span><span class="o">.</span><span class="n">textedit</span><span class="o">.</span><span class="n">appendHtml</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>

  3791. 

  3792.     <span class="nd">@Slot</span><span class="p">()</span>

  3793.     <span class="k">def</span> <span class="nf">manual_update</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3794.         <span class="c1"># This function uses the formatted message passed in, but also uses</span>

  3795.         <span class="c1"># information from the record to format the message in an appropriate</span>

  3796.         <span class="c1"># color according to its severity (level).</span>

  3797.         <span class="n">level</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">LEVELS</span><span class="p">)</span>

  3798.         <span class="n">extra</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;qThreadName&#39;</span><span class="p">:</span> <span class="n">ctname</span><span class="p">()</span> <span class="p">}</span>

  3799.         <span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">level</span><span class="p">,</span> <span class="s1">&#39;Manually logged!&#39;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">extra</span><span class="p">)</span>

  3800. 

  3801.     <span class="nd">@Slot</span><span class="p">()</span>

  3802.     <span class="k">def</span> <span class="nf">clear_display</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3803.         <span class="bp">self</span><span class="o">.</span><span class="n">textedit</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>

  3804. 

  3805. 

  3806. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  3807.     <span class="n">QtCore</span><span class="o">.</span><span class="n">QThread</span><span class="o">.</span><span class="n">currentThread</span><span class="p">()</span><span class="o">.</span><span class="n">setObjectName</span><span class="p">(</span><span class="s1">&#39;MainThread&#39;</span><span class="p">)</span>

  3808.     <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3809.     <span class="n">app</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QApplication</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">)</span>

  3810.     <span class="n">example</span> <span class="o">=</span> <span class="n">Window</span><span class="p">(</span><span class="n">app</span><span class="p">)</span>

  3811.     <span class="n">example</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>

  3812.     <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">app</span><span class="p">,</span> <span class="s1">&#39;exec&#39;</span><span class="p">):</span>

  3813.         <span class="n">rc</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">exec</span><span class="p">()</span>

  3814.     <span class="k">else</span><span class="p">:</span>

  3815.         <span class="n">rc</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">exec_</span><span class="p">()</span>

  3816.     <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">rc</span><span class="p">)</span>

  3817. 

  3818. <span class="k">if</span> <span class="vm">__name__</span><span class="o">==</span><span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  3819.     <span class="n">main</span><span class="p">()</span>

  3820. </pre></div>

  3821. </div>

  3822. </section>

  3823. <section id="logging-to-syslog-with-rfc5424-support">

  3824. <h2>Logging to syslog with RFC5424 support<a class="headerlink" href="#logging-to-syslog-with-rfc5424-support" title="Link to this heading">¶</a></h2>

  3825. <p>Although <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5424.html"><strong>RFC 5424</strong></a> dates from 2009, most syslog servers are configured by default to

  3826. use the older <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3164.html"><strong>RFC 3164</strong></a>, which hails from 2001. When <code class="docutils literal notranslate"><span class="pre">logging</span></code> was added to Python

  3827. in 2003, it supported the earlier (and only existing) protocol at the time. Since

  3828. RFC5424 came out, as there has not been widespread deployment of it in syslog

  3829. servers, the <a class="reference internal" href="../library/logging.handlers.html#logging.handlers.SysLogHandler" title="logging.handlers.SysLogHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">SysLogHandler</span></code></a> functionality has not been

  3830. updated.</p>

  3831. <p>RFC 5424 contains some useful features such as support for structured data, and if you

  3832. need to be able to log to a syslog server with support for it, you can do so with a

  3833. subclassed handler which looks something like this:</p>

  3834. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">datetime</span>

  3835. <span class="kn">import</span> <span class="nn">logging.handlers</span>

  3836. <span class="kn">import</span> <span class="nn">re</span>

  3837. <span class="kn">import</span> <span class="nn">socket</span>

  3838. <span class="kn">import</span> <span class="nn">time</span>

  3839. 

  3840. <span class="k">class</span> <span class="nc">SysLogHandler5424</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">handlers</span><span class="o">.</span><span class="n">SysLogHandler</span><span class="p">):</span>

  3841. 

  3842.     <span class="n">tz_offset</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="sa">r</span><span class="s1">&#39;([+-]\d</span><span class="si">{2}</span><span class="s1">)(\d</span><span class="si">{2}</span><span class="s1">)$&#39;</span><span class="p">)</span>

  3843.     <span class="n">escaped</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="sa">r</span><span class="s1">&#39;([\]&quot;</span><span class="se">\\</span><span class="s1">])&#39;</span><span class="p">)</span>

  3844. 

  3845.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  3846.         <span class="bp">self</span><span class="o">.</span><span class="n">msgid</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s1">&#39;msgid&#39;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>

  3847.         <span class="bp">self</span><span class="o">.</span><span class="n">appname</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s1">&#39;appname&#39;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>

  3848.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  3849. 

  3850.     <span class="k">def</span> <span class="nf">format</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">record</span><span class="p">):</span>

  3851.         <span class="n">version</span> <span class="o">=</span> <span class="mi">1</span>

  3852.         <span class="n">asctime</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">created</span><span class="p">)</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>

  3853.         <span class="n">m</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">tz_offset</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s1">&#39;%z&#39;</span><span class="p">))</span>

  3854.         <span class="n">has_offset</span> <span class="o">=</span> <span class="kc">False</span>

  3855.         <span class="k">if</span> <span class="n">m</span> <span class="ow">and</span> <span class="n">time</span><span class="o">.</span><span class="n">timezone</span><span class="p">:</span>

  3856.             <span class="n">hrs</span><span class="p">,</span> <span class="n">mins</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">groups</span><span class="p">()</span>

  3857.             <span class="k">if</span> <span class="nb">int</span><span class="p">(</span><span class="n">hrs</span><span class="p">)</span> <span class="ow">or</span> <span class="nb">int</span><span class="p">(</span><span class="n">mins</span><span class="p">):</span>

  3858.                 <span class="n">has_offset</span> <span class="o">=</span> <span class="kc">True</span>

  3859.         <span class="k">if</span> <span class="ow">not</span> <span class="n">has_offset</span><span class="p">:</span>

  3860.             <span class="n">asctime</span> <span class="o">+=</span> <span class="s1">&#39;Z&#39;</span>

  3861.         <span class="k">else</span><span class="p">:</span>

  3862.             <span class="n">asctime</span> <span class="o">+=</span> <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">hrs</span><span class="si">}</span><span class="s1">:</span><span class="si">{</span><span class="n">mins</span><span class="si">}</span><span class="s1">&#39;</span>

  3863.         <span class="k">try</span><span class="p">:</span>

  3864.             <span class="n">hostname</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">gethostname</span><span class="p">()</span>

  3865.         <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>

  3866.             <span class="n">hostname</span> <span class="o">=</span> <span class="s1">&#39;-&#39;</span>

  3867.         <span class="n">appname</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">appname</span> <span class="ow">or</span> <span class="s1">&#39;-&#39;</span>

  3868.         <span class="n">procid</span> <span class="o">=</span> <span class="n">record</span><span class="o">.</span><span class="n">process</span>

  3869.         <span class="n">msgid</span> <span class="o">=</span> <span class="s1">&#39;-&#39;</span>

  3870.         <span class="n">msg</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>

  3871.         <span class="n">sdata</span> <span class="o">=</span> <span class="s1">&#39;-&#39;</span>

  3872.         <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">record</span><span class="p">,</span> <span class="s1">&#39;structured_data&#39;</span><span class="p">):</span>

  3873.             <span class="n">sd</span> <span class="o">=</span> <span class="n">record</span><span class="o">.</span><span class="n">structured_data</span>

  3874.             <span class="c1"># This should be a dict where the keys are SD-ID and the value is a</span>

  3875.             <span class="c1"># dict mapping PARAM-NAME to PARAM-VALUE (refer to the RFC for what these</span>

  3876.             <span class="c1"># mean)</span>

  3877.             <span class="c1"># There&#39;s no error checking here - it&#39;s purely for illustration, and you</span>

  3878.             <span class="c1"># can adapt this code for use in production environments</span>

  3879.             <span class="n">parts</span> <span class="o">=</span> <span class="p">[]</span>

  3880. 

  3881.             <span class="k">def</span> <span class="nf">replacer</span><span class="p">(</span><span class="n">m</span><span class="p">):</span>

  3882.                 <span class="n">g</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">groups</span><span class="p">()</span>

  3883.                 <span class="k">return</span> <span class="s1">&#39;</span><span class="se">\\</span><span class="s1">&#39;</span> <span class="o">+</span> <span class="n">g</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

  3884. 

  3885.             <span class="k">for</span> <span class="n">sdid</span><span class="p">,</span> <span class="n">dv</span> <span class="ow">in</span> <span class="n">sd</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  3886.                 <span class="n">part</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;[</span><span class="si">{</span><span class="n">sdid</span><span class="si">}</span><span class="s1">&#39;</span>

  3887.                 <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">dv</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  3888.                     <span class="n">s</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>

  3889.                     <span class="n">s</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">escaped</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="n">replacer</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>

  3890.                     <span class="n">part</span> <span class="o">+=</span> <span class="sa">f</span><span class="s1">&#39; </span><span class="si">{</span><span class="n">k</span><span class="si">}</span><span class="s1">=&quot;</span><span class="si">{</span><span class="n">s</span><span class="si">}</span><span class="s1">&quot;&#39;</span>

  3891.                 <span class="n">part</span> <span class="o">+=</span> <span class="s1">&#39;]&#39;</span>

  3892.                 <span class="n">parts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">part</span><span class="p">)</span>

  3893.             <span class="n">sdata</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">parts</span><span class="p">)</span>

  3894.         <span class="k">return</span> <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">version</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">asctime</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">hostname</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">appname</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">procid</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">msgid</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">sdata</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">msg</span><span class="si">}</span><span class="s1">&#39;</span>

  3895. </pre></div>

  3896. </div>

  3897. <p>You’ll need to be familiar with RFC 5424 to fully understand the above code, and it

  3898. may be that you have slightly different needs (e.g. for how you pass structural data

  3899. to the log). Nevertheless, the above should be adaptable to your speciric needs. With

  3900. the above handler, you’d pass structured data using something like this:</p>

  3901. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sd</span> <span class="o">=</span> <span class="p">{</span>

  3902.     <span class="s1">&#39;foo@12345&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;bar&#39;</span><span class="p">:</span> <span class="s1">&#39;baz&#39;</span><span class="p">,</span> <span class="s1">&#39;baz&#39;</span><span class="p">:</span> <span class="s1">&#39;bozz&#39;</span><span class="p">,</span> <span class="s1">&#39;fizz&#39;</span><span class="p">:</span> <span class="sa">r</span><span class="s1">&#39;buzz&#39;</span><span class="p">},</span>

  3903.     <span class="s1">&#39;foo@54321&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;rab&#39;</span><span class="p">:</span> <span class="s1">&#39;baz&#39;</span><span class="p">,</span> <span class="s1">&#39;zab&#39;</span><span class="p">:</span> <span class="s1">&#39;bozz&#39;</span><span class="p">,</span> <span class="s1">&#39;zzif&#39;</span><span class="p">:</span> <span class="sa">r</span><span class="s1">&#39;buzz&#39;</span><span class="p">}</span>

  3904. <span class="p">}</span>

  3905. <span class="n">extra</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;structured_data&#39;</span><span class="p">:</span> <span class="n">sd</span><span class="p">}</span>

  3906. <span class="n">i</span> <span class="o">=</span> <span class="mi">1</span>

  3907. <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s1">&#39;Message </span><span class="si">%d</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">extra</span><span class="p">)</span>

  3908. </pre></div>

  3909. </div>

  3910. </section>

  3911. <section id="how-to-treat-a-logger-like-an-output-stream">

  3912. <h2>How to treat a logger like an output stream<a class="headerlink" href="#how-to-treat-a-logger-like-an-output-stream" title="Link to this heading">¶</a></h2>

  3913. <p>Sometimes, you need to interface to a third-party API which expects a file-like

  3914. object to write to, but you want to direct the API’s output to a logger. You

  3915. can do this using a class which wraps a logger with a file-like API.

  3916. Here’s a short script illustrating such a class:</p>

  3917. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>

  3918. 

  3919. <span class="k">class</span> <span class="nc">LoggerWriter</span><span class="p">:</span>

  3920.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="p">):</span>

  3921.         <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logger</span>

  3922.         <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="n">level</span>

  3923. 

  3924.     <span class="k">def</span> <span class="nf">write</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>

  3925.         <span class="k">if</span> <span class="n">message</span> <span class="o">!=</span> <span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">:</span>  <span class="c1"># avoid printing bare newlines, if you like</span>

  3926.             <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">level</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>

  3927. 

  3928.     <span class="k">def</span> <span class="nf">flush</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3929.         <span class="c1"># doesn&#39;t actually do anything, but might be expected of a file-like</span>

  3930.         <span class="c1"># object - so optional depending on your situation</span>

  3931.         <span class="k">pass</span>

  3932. 

  3933.     <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  3934.         <span class="c1"># doesn&#39;t actually do anything, but might be expected of a file-like</span>

  3935.         <span class="c1"># object - so optional depending on your situation. You might want</span>

  3936.         <span class="c1"># to set a flag so that later calls to write raise an exception</span>

  3937.         <span class="k">pass</span>

  3938. 

  3939. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  3940.     <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3941.     <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">&#39;demo&#39;</span><span class="p">)</span>

  3942.     <span class="n">info_fp</span> <span class="o">=</span> <span class="n">LoggerWriter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  3943.     <span class="n">debug_fp</span> <span class="o">=</span> <span class="n">LoggerWriter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

  3944.     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;An INFO message&#39;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">info_fp</span><span class="p">)</span>

  3945.     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;A DEBUG message&#39;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">debug_fp</span><span class="p">)</span>

  3946. 

  3947. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>

  3948.     <span class="n">main</span><span class="p">()</span>

  3949. </pre></div>

  3950. </div>

  3951. <p>When this script is run, it prints</p>

  3952. <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>INFO:demo:An INFO message

  3953. DEBUG:demo:A DEBUG message

  3954. </pre></div>

  3955. </div>

  3956. <p>You could also use <code class="docutils literal notranslate"><span class="pre">LoggerWriter</span></code> to redirect <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> and

  3957. <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> by doing something like this:</p>

  3958. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>

  3959. 

  3960. <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">LoggerWriter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>

  3961. <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span> <span class="o">=</span> <span class="n">LoggerWriter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">)</span>

  3962. </pre></div>

  3963. </div>

  3964. <p>You should do this <em>after</em> configuring logging for your needs. In the above

  3965. example, the <a class="reference internal" href="../library/logging.html#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> call does this (using the

  3966. <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> value <em>before</em> it is overwritten by a <code class="docutils literal notranslate"><span class="pre">LoggerWriter</span></code>

  3967. instance). Then, you’d get this kind of result:</p>

  3968. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Foo&#39;</span><span class="p">)</span>

  3969. <span class="go">INFO:demo:Foo</span>

  3970. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Bar&#39;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>

  3971. <span class="go">WARNING:demo:Bar</span>

  3972. <span class="gp">&gt;&gt;&gt;</span>

  3973. </pre></div>

  3974. </div>

  3975. <p>Of course, the examples above show output according to the format used by

  3976. <a class="reference internal" href="../library/logging.html#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a>, but you can use a different formatter when you

  3977. configure logging.</p>

  3978. <p>Note that with the above scheme, you are somewhat at the mercy of buffering and

  3979. the sequence of write calls which you are intercepting. For example, with the

  3980. definition of <code class="docutils literal notranslate"><span class="pre">LoggerWriter</span></code> above, if you have the snippet</p>

  3981. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span> <span class="o">=</span> <span class="n">LoggerWriter</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">)</span>

  3982. <span class="mi">1</span> <span class="o">/</span> <span class="mi">0</span>

  3983. </pre></div>

  3984. </div>

  3985. <p>then running the script results in</p>

  3986. <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>WARNING:demo:Traceback (most recent call last):

  3987. 

  3988. WARNING:demo:  File &quot;/home/runner/cookbook-loggerwriter/test.py&quot;, line 53, in &lt;module&gt;

  3989. 

  3990. WARNING:demo:

  3991. WARNING:demo:main()

  3992. WARNING:demo:  File &quot;/home/runner/cookbook-loggerwriter/test.py&quot;, line 49, in main

  3993. 

  3994. WARNING:demo:

  3995. WARNING:demo:1 / 0

  3996. WARNING:demo:ZeroDivisionError

  3997. WARNING:demo::

  3998. WARNING:demo:division by zero

  3999. </pre></div>

  4000. </div>

  4001. <p>As you can see, this output isn’t ideal. That’s because the underlying code

  4002. which writes to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> makes multiple writes, each of which results in a

  4003. separate logged line (for example, the last three lines above). To get around

  4004. this problem, you need to buffer things and only output log lines when newlines

  4005. are seen. Let’s use a slghtly better implementation of <code class="docutils literal notranslate"><span class="pre">LoggerWriter</span></code>:</p>

  4006. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BufferingLoggerWriter</span><span class="p">(</span><span class="n">LoggerWriter</span><span class="p">):</span>

  4007.     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="p">):</span>

  4008.         <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">logger</span><span class="p">,</span> <span class="n">level</span><span class="p">)</span>

  4009.         <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>

  4010. 

  4011.     <span class="k">def</span> <span class="nf">write</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>

  4012.         <span class="k">if</span> <span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">message</span><span class="p">:</span>

  4013.             <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">+=</span> <span class="n">message</span>

  4014.         <span class="k">else</span><span class="p">:</span>

  4015.             <span class="n">parts</span> <span class="o">=</span> <span class="n">message</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)</span>

  4016.             <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">:</span>

  4017.                 <span class="n">s</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">+</span> <span class="n">parts</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>

  4018.                 <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">level</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>

  4019.             <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="n">parts</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>

  4020.             <span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">parts</span><span class="p">:</span>

  4021.                 <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">level</span><span class="p">,</span> <span class="n">part</span><span class="p">)</span>

  4022. </pre></div>

  4023. </div>

  4024. <p>This just buffers up stuff until a newline is seen, and then logs complete

  4025. lines. With this approach, you get better output:</p>

  4026. <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>WARNING:demo:Traceback (most recent call last):

  4027. WARNING:demo:  File &quot;/home/runner/cookbook-loggerwriter/main.py&quot;, line 55, in &lt;module&gt;

  4028. WARNING:demo:    main()

  4029. WARNING:demo:  File &quot;/home/runner/cookbook-loggerwriter/main.py&quot;, line 52, in main

  4030. WARNING:demo:    1/0

  4031. WARNING:demo:ZeroDivisionError: division by zero

  4032. </pre></div>

  4033. </div>

  4034. </section>

  4035. <section id="patterns-to-avoid">

  4036. <h2>Patterns to avoid<a class="headerlink" href="#patterns-to-avoid" title="Link to this heading">¶</a></h2>

  4037. <p>Although the preceding sections have described ways of doing things you might

  4038. need to do or deal with, it is worth mentioning some usage patterns which are

  4039. <em>unhelpful</em>, and which should therefore be avoided in most cases. The following

  4040. sections are in no particular order.</p>

  4041. <section id="opening-the-same-log-file-multiple-times">

  4042. <h3>Opening the same log file multiple times<a class="headerlink" href="#opening-the-same-log-file-multiple-times" title="Link to this heading">¶</a></h3>

  4043. <p>On Windows, you will generally not be able to open the same file multiple times

  4044. as this will lead to a “file is in use by another process” error. However, on

  4045. POSIX platforms you’ll not get any errors if you open the same file multiple

  4046. times. This could be done accidentally, for example by:</p>

  4047. <ul class="simple">

  4048. <li><p>Adding a file handler more than once which references the same file (e.g. by

  4049. a copy/paste/forget-to-change error).</p></li>

  4050. <li><p>Opening two files that look different, as they have different names, but are

  4051. the same because one is a symbolic link to the other.</p></li>

  4052. <li><p>Forking a process, following which both parent and child have a reference to

  4053. the same file. This might be through use of the <a class="reference internal" href="../library/multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module,

  4054. for example.</p></li>

  4055. </ul>

  4056. <p>Opening a file multiple times might <em>appear</em> to work most of the time, but can

  4057. lead to a number of problems in practice:</p>

  4058. <ul class="simple">

  4059. <li><p>Logging output can be garbled because multiple threads or processes try to

  4060. write to the same file. Although logging guards against concurrent use of the

  4061. same handler instance by multiple threads, there is no such protection if

  4062. concurrent writes are attempted by two different threads using two different

  4063. handler instances which happen to point to the same file.</p></li>

  4064. <li><p>An attempt to delete a file (e.g. during file rotation) silently fails,

  4065. because there is another reference pointing to it. This can lead to confusion

  4066. and wasted debugging time - log entries end up in unexpected places, or are

  4067. lost altogether. Or a file that was supposed to be moved remains in place,

  4068. and grows in size unexpectedly despite size-based rotation being supposedly

  4069. in place.</p></li>

  4070. </ul>

  4071. <p>Use the techniques outlined in <a class="reference internal" href="#multiple-processes"><span class="std std-ref">Logging to a single file from multiple processes</span></a> to circumvent such

  4072. issues.</p>

  4073. </section>

  4074. <section id="using-loggers-as-attributes-in-a-class-or-passing-them-as-parameters">

  4075. <h3>Using loggers as attributes in a class or passing them as parameters<a class="headerlink" href="#using-loggers-as-attributes-in-a-class-or-passing-them-as-parameters" title="Link to this heading">¶</a></h3>

  4076. <p>While there might be unusual cases where you’ll need to do this, in general

  4077. there is no point because loggers are singletons. Code can always access a

  4078. given logger instance by name using <code class="docutils literal notranslate"><span class="pre">logging.getLogger(name)</span></code>, so passing

  4079. instances around and holding them as instance attributes is pointless. Note

  4080. that in other languages such as Java and C#, loggers are often static class

  4081. attributes. However, this pattern doesn’t make sense in Python, where the

  4082. module (and not the class) is the unit of software decomposition.</p>

  4083. </section>

  4084. <section id="adding-handlers-other-than-nullhandler-to-a-logger-in-a-library">

  4085. <h3>Adding handlers other than <a class="reference internal" href="../library/logging.handlers.html#logging.NullHandler" title="logging.NullHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullHandler</span></code></a> to a logger in a library<a class="headerlink" href="#adding-handlers-other-than-nullhandler-to-a-logger-in-a-library" title="Link to this heading">¶</a></h3>

  4086. <p>Configuring logging by adding handlers, formatters and filters is the

  4087. responsibility of the application developer, not the library developer. If you

  4088. are maintaining a library, ensure that you don’t add handlers to any of your

  4089. loggers other than a <a class="reference internal" href="../library/logging.handlers.html#logging.NullHandler" title="logging.NullHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullHandler</span></code></a> instance.</p>

  4090. </section>

  4091. <section id="creating-a-lot-of-loggers">

  4092. <h3>Creating a lot of loggers<a class="headerlink" href="#creating-a-lot-of-loggers" title="Link to this heading">¶</a></h3>

  4093. <p>Loggers are singletons that are never freed during a script execution, and so

  4094. creating lots of loggers will use up memory which can’t then be freed. Rather

  4095. than create a logger per e.g. file processed or network connection made, use

  4096. the <a class="reference internal" href="#context-info"><span class="std std-ref">existing mechanisms</span></a> for passing contextual

  4097. information into your logs and restrict the loggers created to those describing

  4098. areas within your application (generally modules, but occasionally slightly

  4099. more fine-grained than that).</p>

  4100. </section>

  4101. </section>

  4102. <section id="other-resources">

  4103. <span id="cookbook-ref-links"></span><h2>Other resources<a class="headerlink" href="#other-resources" title="Link to this heading">¶</a></h2>

  4104. <div class="admonition seealso">

  4105. <p class="admonition-title">See also</p>

  4106. <dl class="simple">

  4107. <dt>Module <a class="reference internal" href="../library/logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a></dt><dd><p>API reference for the logging module.</p>

  4108. </dd>

  4109. <dt>Module <a class="reference internal" href="../library/logging.config.html#module-logging.config" title="logging.config: Configuration of the logging module."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code></a></dt><dd><p>Configuration API for the logging module.</p>

  4110. </dd>

  4111. <dt>Module <a class="reference internal" href="../library/logging.handlers.html#module-logging.handlers" title="logging.handlers: Handlers for the logging module."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.handlers</span></code></a></dt><dd><p>Useful handlers included with the logging module.</p>

  4112. </dd>

  4113. </dl>

  4114. <p><a class="reference internal" href="logging.html#logging-basic-tutorial"><span class="std std-ref">Basic Tutorial</span></a></p>

  4115. <p><a class="reference internal" href="logging.html#logging-advanced-tutorial"><span class="std std-ref">Advanced Tutorial</span></a></p>

  4116. </div>

  4117. </section>

  4118. </section>

  4119. 

  4120. 

  4121.             <div class="clearer"></div>

  4122.           </div>

  4123.         </div>

  4124.       </div>

  4125.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  4126.         <div class="sphinxsidebarwrapper">

  4127.   <div>

  4128.     <h3><a href="../contents.html">Table of Contents</a></h3>

  4129.     <ul>

  4130. <li><a class="reference internal" href="#">Logging Cookbook</a><ul>

  4131. <li><a class="reference internal" href="#using-logging-in-multiple-modules">Using logging in multiple modules</a></li>

  4132. <li><a class="reference internal" href="#logging-from-multiple-threads">Logging from multiple threads</a></li>

  4133. <li><a class="reference internal" href="#multiple-handlers-and-formatters">Multiple handlers and formatters</a></li>

  4134. <li><a class="reference internal" href="#logging-to-multiple-destinations">Logging to multiple destinations</a></li>

  4135. <li><a class="reference internal" href="#custom-handling-of-levels">Custom handling of levels</a></li>

  4136. <li><a class="reference internal" href="#configuration-server-example">Configuration server example</a></li>

  4137. <li><a class="reference internal" href="#dealing-with-handlers-that-block">Dealing with handlers that block</a></li>

  4138. <li><a class="reference internal" href="#sending-and-receiving-logging-events-across-a-network">Sending and receiving logging events across a network</a><ul>

  4139. <li><a class="reference internal" href="#running-a-logging-socket-listener-in-production">Running a logging socket listener in production</a></li>

  4140. </ul>

  4141. </li>

  4142. <li><a class="reference internal" href="#adding-contextual-information-to-your-logging-output">Adding contextual information to your logging output</a><ul>

  4143. <li><a class="reference internal" href="#using-loggeradapters-to-impart-contextual-information">Using LoggerAdapters to impart contextual information</a><ul>

  4144. <li><a class="reference internal" href="#using-objects-other-than-dicts-to-pass-contextual-information">Using objects other than dicts to pass contextual information</a></li>

  4145. </ul>

  4146. </li>

  4147. <li><a class="reference internal" href="#using-filters-to-impart-contextual-information">Using Filters to impart contextual information</a></li>

  4148. </ul>

  4149. </li>

  4150. <li><a class="reference internal" href="#use-of-contextvars">Use of <code class="docutils literal notranslate"><span class="pre">contextvars</span></code></a></li>

  4151. <li><a class="reference internal" href="#imparting-contextual-information-in-handlers">Imparting contextual information in handlers</a></li>

  4152. <li><a class="reference internal" href="#logging-to-a-single-file-from-multiple-processes">Logging to a single file from multiple processes</a><ul>

  4153. <li><a class="reference internal" href="#using-concurrent-futures-processpoolexecutor">Using concurrent.futures.ProcessPoolExecutor</a></li>

  4154. <li><a class="reference internal" href="#deploying-web-applications-using-gunicorn-and-uwsgi">Deploying Web applications using Gunicorn and uWSGI</a></li>

  4155. </ul>

  4156. </li>

  4157. <li><a class="reference internal" href="#using-file-rotation">Using file rotation</a></li>

  4158. <li><a class="reference internal" href="#use-of-alternative-formatting-styles">Use of alternative formatting styles</a></li>

  4159. <li><a class="reference internal" href="#customizing-logrecord">Customizing <code class="docutils literal notranslate"><span class="pre">LogRecord</span></code></a></li>

  4160. <li><a class="reference internal" href="#subclassing-queuehandler-and-queuelistener-a-zeromq-example">Subclassing QueueHandler and QueueListener- a ZeroMQ example</a><ul>

  4161. <li><a class="reference internal" href="#subclass-queuehandler">Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code></a></li>

  4162. <li><a class="reference internal" href="#subclass-queuelistener">Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code></a></li>

  4163. </ul>

  4164. </li>

  4165. <li><a class="reference internal" href="#subclassing-queuehandler-and-queuelistener-a-pynng-example">Subclassing QueueHandler and QueueListener- a <code class="docutils literal notranslate"><span class="pre">pynng</span></code> example</a><ul>

  4166. <li><a class="reference internal" href="#id3">Subclass <code class="docutils literal notranslate"><span class="pre">QueueListener</span></code></a></li>

  4167. <li><a class="reference internal" href="#id4">Subclass <code class="docutils literal notranslate"><span class="pre">QueueHandler</span></code></a></li>

  4168. </ul>

  4169. </li>

  4170. <li><a class="reference internal" href="#an-example-dictionary-based-configuration">An example dictionary-based configuration</a></li>

  4171. <li><a class="reference internal" href="#using-a-rotator-and-namer-to-customize-log-rotation-processing">Using a rotator and namer to customize log rotation processing</a></li>

  4172. <li><a class="reference internal" href="#a-more-elaborate-multiprocessing-example">A more elaborate multiprocessing example</a></li>

  4173. <li><a class="reference internal" href="#inserting-a-bom-into-messages-sent-to-a-sysloghandler">Inserting a BOM into messages sent to a SysLogHandler</a></li>

  4174. <li><a class="reference internal" href="#implementing-structured-logging">Implementing structured logging</a></li>

  4175. <li><a class="reference internal" href="#customizing-handlers-with-dictconfig">Customizing handlers with <code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a></li>

  4176. <li><a class="reference internal" href="#using-particular-formatting-styles-throughout-your-application">Using particular formatting styles throughout your application</a><ul>

  4177. <li><a class="reference internal" href="#using-logrecord-factories">Using LogRecord factories</a></li>

  4178. <li><a class="reference internal" href="#using-custom-message-objects">Using custom message objects</a></li>

  4179. </ul>

  4180. </li>

  4181. <li><a class="reference internal" href="#configuring-filters-with-dictconfig">Configuring filters with <code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a></li>

  4182. <li><a class="reference internal" href="#customized-exception-formatting">Customized exception formatting</a></li>

  4183. <li><a class="reference internal" href="#speaking-logging-messages">Speaking logging messages</a></li>

  4184. <li><a class="reference internal" href="#buffering-logging-messages-and-outputting-them-conditionally">Buffering logging messages and outputting them conditionally</a></li>

  4185. <li><a class="reference internal" href="#sending-logging-messages-to-email-with-buffering">Sending logging messages to email, with buffering</a></li>

  4186. <li><a class="reference internal" href="#formatting-times-using-utc-gmt-via-configuration">Formatting times using UTC (GMT) via configuration</a></li>

  4187. <li><a class="reference internal" href="#using-a-context-manager-for-selective-logging">Using a context manager for selective logging</a></li>

  4188. <li><a class="reference internal" href="#a-cli-application-starter-template">A CLI application starter template</a></li>

  4189. <li><a class="reference internal" href="#a-qt-gui-for-logging">A Qt GUI for logging</a></li>

  4190. <li><a class="reference internal" href="#logging-to-syslog-with-rfc5424-support">Logging to syslog with RFC5424 support</a></li>

  4191. <li><a class="reference internal" href="#how-to-treat-a-logger-like-an-output-stream">How to treat a logger like an output stream</a></li>

  4192. <li><a class="reference internal" href="#patterns-to-avoid">Patterns to avoid</a><ul>

  4193. <li><a class="reference internal" href="#opening-the-same-log-file-multiple-times">Opening the same log file multiple times</a></li>

  4194. <li><a class="reference internal" href="#using-loggers-as-attributes-in-a-class-or-passing-them-as-parameters">Using loggers as attributes in a class or passing them as parameters</a></li>

  4195. <li><a class="reference internal" href="#adding-handlers-other-than-nullhandler-to-a-logger-in-a-library">Adding handlers other than <code class="xref py py-class docutils literal notranslate"><span class="pre">NullHandler</span></code> to a logger in a library</a></li>

  4196. <li><a class="reference internal" href="#creating-a-lot-of-loggers">Creating a lot of loggers</a></li>

  4197. </ul>

  4198. </li>

  4199. <li><a class="reference internal" href="#other-resources">Other resources</a></li>

  4200. </ul>

  4201. </li>

  4202. </ul>

  4203. 

  4204.   </div>

  4205.   <div>

  4206.     <h4>Previous topic</h4>

  4207.     <p class="topless"><a href="logging.html"

  4208.                           title="previous chapter">Logging HOWTO</a></p>

  4209.   </div>

  4210.   <div>

  4211.     <h4>Next topic</h4>

  4212.     <p class="topless"><a href="regex.html"

  4213.                           title="next chapter">Regular Expression HOWTO</a></p>

  4214.   </div>

  4215.   <div role="note" aria-label="source link">

  4216.     <h3>This Page</h3>

  4217.     <ul class="this-page-menu">

  4218.       <li><a href="../bugs.html">Report a Bug</a></li>

  4219.       <li>

  4220.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/logging-cookbook.rst"

  4221.             rel="nofollow">Show Source

  4222.         </a>

  4223.       </li>

  4224.     </ul>

  4225.   </div>

  4226.         </div>

  4227. <div id="sidebarbutton" title="Collapse sidebar">

  4228. <span>«</span>

  4229. </div>

  4230. 

  4231.       </div>

  4232.       <div class="clearer"></div>

  4233.     </div>  

  4234.     <div class="related" role="navigation" aria-label="related navigation">

  4235.       <h3>Navigation</h3>

  4236.       <ul>

  4237.         <li class="right" style="margin-right: 10px">

  4238.           <a href="../genindex.html" title="General Index"

  4239.              >index</a></li>

  4240.         <li class="right" >

  4241.           <a href="../py-modindex.html" title="Python Module Index"

  4242.              >modules</a> |</li>

  4243.         <li class="right" >

  4244.           <a href="regex.html" title="Regular Expression HOWTO"

  4245.              >next</a> |</li>

  4246.         <li class="right" >

  4247.           <a href="logging.html" title="Logging HOWTO"

  4248.              >previous</a> |</li>

  4249. 

  4250.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  4251.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  4252.           <li class="switchers">

  4253.             <div class="language_switcher_placeholder"></div>

  4254.             <div class="version_switcher_placeholder"></div>

  4255.           </li>

  4256.           <li>

  4257.               

  4258.           </li>

  4259.     <li id="cpython-language-and-version">

  4260.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  4261.     </li>

  4262. 

  4263.           <li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> &#187;</li>

  4264.         <li class="nav-item nav-item-this"><a href="">Logging Cookbook</a></li>

  4265.                 <li class="right">

  4266.                     

  4267. 

  4268.     <div class="inline-search" role="search">

  4269.         <form class="inline-search" action="../search.html" method="get">

  4270.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  4271.           <input type="submit" value="Go" />

  4272.         </form>

  4273.     </div>

  4274.                      |

  4275.                 </li>

  4276.             <li class="right">

  4277. <label class="theme-selector-label">

  4278.     Theme

  4279.     <select class="theme-selector" oninput="activateTheme(this.value)">

  4280.         <option value="auto" selected>Auto</option>

  4281.         <option value="light">Light</option>

  4282.         <option value="dark">Dark</option>

  4283.     </select>

  4284. </label> |</li>

  4285.             

  4286.       </ul>

  4287.     </div>  

  4288.     <div class="footer">

  4289.     &copy; 

  4290.       <a href="../copyright.html">

  4291.     

  4292.     Copyright

  4293.     

  4294.       </a>

  4295.      2001-2024, Python Software Foundation.

  4296.     <br />

  4297.     This page is licensed under the Python Software Foundation License Version 2.

  4298.     <br />

  4299.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  4300.     <br />

  4301.     

  4302.       See <a href="/license.html">History and License</a> for more information.<br />

  4303.     

  4304.     

  4305.     <br />

  4306. 

  4307.     The Python Software Foundation is a non-profit corporation.

  4308. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  4309. <br />

  4310.     <br />

  4311.       Last updated on Apr 09, 2024 (13:47 UTC).

  4312.     

  4313.       <a href="/bugs.html">Found a bug</a>?

  4314.     

  4315.     <br />

  4316. 

  4317.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  4318.     </div>

  4319. 

  4320.   </body>

  4321. </html>
上海开阖软件有限公司 沪ICP备12045867号-1