mirror of https://github.com/hpcaitech/ColossalAI
aibig-modeldata-parallelismdeep-learningdistributed-computingfoundation-modelsheterogeneous-traininghpcinferencelarge-scalemodel-parallelismpipeline-parallelism
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.
1970 lines
198 KiB
1970 lines
198 KiB
<!DOCTYPE html> |
|
<!-- saved from url=(0046)https://docs.python.org/3/library/logging.html --> |
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/"> |
|
<meta property="og:title" content="logging — Logging facility for Python"> |
|
<meta property="og:type" content="website"> |
|
<meta property="og:url" content="https://docs.python.org/3/library/logging.html"> |
|
<meta property="og:site_name" content="Python documentation"> |
|
<meta property="og:description" content="Source code: Lib/logging/__init__.py Important: This page contains the API reference information. For tutorial information and discussion of more advanced topics, see Basic Tutorial, Advanced Tutor..."> |
|
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png"> |
|
<meta property="og:image:alt" content="Python documentation"> |
|
<meta name="description" content="Source code: Lib/logging/__init__.py Important: This page contains the API reference information. For tutorial information and discussion of more advanced topics, see Basic Tutorial, Advanced Tutor..."> |
|
<meta property="og:image:width" content="200"> |
|
<meta property="og:image:height" content="200"> |
|
<meta name="theme-color" content="#3776ab"> |
|
|
|
<title>logging — Logging facility for Python — Python 3.11.5 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0"> |
|
|
|
<link rel="stylesheet" type="text/css" href="./test_files/pygments.css"> |
|
<link rel="stylesheet" type="text/css" href="./test_files/pydoctheme.css"> |
|
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="./test_files/pygments_dark.css"> |
|
|
|
<script data-url_root="../" id="documentation_options" src="./test_files/documentation_options.js.download"></script> |
|
<script src="./test_files/jquery.js.download"></script> |
|
<script src="./test_files/underscore.js.download"></script> |
|
<script src="./test_files/doctools.js.download"></script> |
|
|
|
<script src="./test_files/sidebar.js.download"></script> |
|
|
|
<link rel="search" type="application/opensearchdescription+xml" title="Search within Python 3.11.5 documentation" href="https://docs.python.org/3/_static/opensearch.xml"> |
|
<link rel="author" title="About these documents" href="https://docs.python.org/3/about.html"> |
|
<link rel="index" title="Index" href="https://docs.python.org/3/genindex.html"> |
|
<link rel="search" title="Search" href="https://docs.python.org/3/search.html"> |
|
<link rel="copyright" title="Copyright" href="https://docs.python.org/3/copyright.html"> |
|
<link rel="next" title="logging.config — Logging configuration" href="https://docs.python.org/3/library/logging.config.html"> |
|
<link rel="prev" title="getopt — C-style parser for command line options" href="https://docs.python.org/3/library/getopt.html"> |
|
<link rel="canonical" href="https://docs.python.org/3/library/logging.html"> |
|
|
|
|
|
|
|
|
|
|
|
<style> |
|
@media only screen { |
|
table.full-width-table { |
|
width: 100%; |
|
} |
|
} |
|
</style> |
|
<link rel="stylesheet" href="./test_files/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css"> |
|
<link rel="shortcut icon" type="image/png" href="./test_files/py.svg"> |
|
<script type="text/javascript" src="./test_files/copybutton.js.download"></script> |
|
<script type="text/javascript" src="./test_files/menu.js.download"></script> |
|
<script type="text/javascript" src="./test_files/themetoggle.js.download"></script> |
|
|
|
</head> |
|
<body data-new-gr-c-s-check-loaded="14.1038.0" data-gr-ext-installed=""> |
|
<div class="mobile-nav"> |
|
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation" aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> |
|
<nav class="nav-content" role="navigation"> |
|
<label for="menuToggler" class="toggler__label"> |
|
<span></span> |
|
</label> |
|
<span class="nav-items-wrapper"> |
|
<a href="https://www.python.org/" class="nav-logo"> |
|
<img src="./test_files/py.svg" alt="Logo"> |
|
</a> |
|
<span class="version_switcher_placeholder"><select id="version_select"><option value="3.13">dev (3.13)</option><option value="3.12">pre (3.12)</option><option value="3.11" selected="selected">3.11.5</option><option value="3.10">3.10</option><option value="3.9">3.9</option><option value="3.8">3.8</option><option value="3.7">3.7</option><option value="3.6">3.6</option><option value="3.5">3.5</option><option value="2.7">2.7</option></select></span> |
|
<form role="search" class="search" action="https://docs.python.org/3/search.html" method="get"> |
|
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon"> |
|
<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> |
|
</svg> |
|
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q"> |
|
<input type="submit" value="Go"> |
|
</form> |
|
</span> |
|
</nav> |
|
<div class="menu-wrapper"> |
|
<nav class="menu" role="navigation" aria-label="main navigation" tabindex="-1"> |
|
<div class="language_switcher_placeholder"><select id="language_select"><option value="en" selected="selected">English</option><option value="es">Spanish</option><option value="fr">French</option><option value="ja">Japanese</option><option value="ko">Korean</option><option value="pt-br">Brazilian Portuguese</option><option value="tr">Turkish</option><option value="zh-cn">Simplified Chinese</option><option value="zh-tw">Traditional Chinese</option></select></div> |
|
|
|
<label class="theme-selector-label"> |
|
Theme |
|
<select class="theme-selector" oninput="activateTheme(this.value)"> |
|
<option value="auto" selected="">Auto</option> |
|
<option value="light">Light</option> |
|
<option value="dark">Dark</option> |
|
</select> |
|
</label> |
|
<div> |
|
<h3><a href="https://docs.python.org/3/contents.html">Table of Contents</a></h3> |
|
<ul> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> — Logging facility for Python</a><ul> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logger-objects">Logger Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging-levels">Logging Levels</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#handler-objects">Handler Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#formatter-objects">Formatter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#filter-objects">Filter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-objects">LogRecord Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-attributes">LogRecord attributes</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#loggeradapter-objects">LoggerAdapter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#thread-safety">Thread Safety</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#module-level-functions">Module-Level Functions</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#module-level-attributes">Module-Level Attributes</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module">Integration with the warnings module</a></li> |
|
</ul> |
|
</li> |
|
</ul> |
|
|
|
</div> |
|
<div> |
|
<h4>Previous topic</h4> |
|
<p class="topless"><a href="https://docs.python.org/3/library/getopt.html" title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> — C-style parser for command line options</a></p> |
|
</div> |
|
<div> |
|
<h4>Next topic</h4> |
|
<p class="topless"><a href="https://docs.python.org/3/library/logging.config.html" title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code> — Logging configuration</a></p> |
|
</div> |
|
<div role="note" aria-label="source link"> |
|
<h3>This Page</h3> |
|
<ul class="this-page-menu"> |
|
<li><a href="https://docs.python.org/3/bugs.html">Report a Bug</a></li> |
|
<li> |
|
<a href="https://github.com/python/cpython/blob/3.11/Doc/library/logging.rst" rel="nofollow">Show Source |
|
</a> |
|
</li> |
|
</ul> |
|
</div> |
|
</nav> |
|
</div> |
|
</div> |
|
|
|
|
|
<div class="related" role="navigation" aria-label="related navigation"> |
|
<h3>Navigation</h3> |
|
<ul> |
|
<li class="right" style="margin-right: 10px"> |
|
<a href="https://docs.python.org/3/genindex.html" title="General Index" accesskey="I">index</a></li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/py-modindex.html" title="Python Module Index">modules</a> |</li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/library/logging.config.html" title="logging.config — Logging configuration" accesskey="N">next</a> |</li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/library/getopt.html" title="getopt — C-style parser for command line options" accesskey="P">previous</a> |</li> |
|
|
|
<li><img src="./test_files/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"></li> |
|
<li><a href="https://www.python.org/">Python</a> »</li> |
|
<li class="switchers"> |
|
<div class="language_switcher_placeholder"><select id="language_select"><option value="en" selected="selected">English</option><option value="es">Spanish</option><option value="fr">French</option><option value="ja">Japanese</option><option value="ko">Korean</option><option value="pt-br">Brazilian Portuguese</option><option value="tr">Turkish</option><option value="zh-cn">Simplified Chinese</option><option value="zh-tw">Traditional Chinese</option></select></div> |
|
<div class="version_switcher_placeholder"><select id="version_select"><option value="3.13">dev (3.13)</option><option value="3.12">pre (3.12)</option><option value="3.11" selected="selected">3.11.5</option><option value="3.10">3.10</option><option value="3.9">3.9</option><option value="3.8">3.8</option><option value="3.7">3.7</option><option value="3.6">3.6</option><option value="3.5">3.5</option><option value="2.7">2.7</option></select></div> |
|
</li> |
|
<li> |
|
|
|
</li> |
|
<li id="cpython-language-and-version"> |
|
<a href="https://docs.python.org/3/index.html">3.11.5 Documentation</a> » |
|
</li> |
|
|
|
<li class="nav-item nav-item-1"><a href="https://docs.python.org/3/library/index.html">The Python Standard Library</a> »</li> |
|
<li class="nav-item nav-item-2"><a href="https://docs.python.org/3/library/allos.html" accesskey="U">Generic Operating System Services</a> »</li> |
|
<li class="nav-item nav-item-this"><a href="https://docs.python.org/3/library/logging.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> — Logging facility for Python</a></li> |
|
<li class="right"> |
|
|
|
|
|
<div class="inline-search" role="search"> |
|
<form class="inline-search" action="https://docs.python.org/3/search.html" method="get"> |
|
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q"> |
|
<input type="submit" value="Go"> |
|
</form> |
|
</div> |
|
| |
|
</li> |
|
<li class="right"> |
|
<label class="theme-selector-label"> |
|
Theme |
|
<select class="theme-selector" oninput="activateTheme(this.value)"> |
|
<option value="auto" selected="">Auto</option> |
|
<option value="light">Light</option> |
|
<option value="dark">Dark</option> |
|
</select> |
|
</label> |</li> |
|
|
|
</ul> |
|
</div> |
|
|
|
<div class="document"> |
|
<div class="documentwrapper"> |
|
<div class="bodywrapper"> |
|
<div class="body" role="main"> |
|
|
|
<section id="module-logging"> |
|
<span id="logging-logging-facility-for-python"></span><h1><a class="reference internal" href="https://docs.python.org/3/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> — Logging facility for Python<a class="headerlink" href="https://docs.python.org/3/library/logging.html#module-logging" title="Permalink to this headline">¶</a></h1> |
|
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.11/Lib/logging/__init__.py">Lib/logging/__init__.py</a></p> |
|
<aside class="sidebar" id="index-0"> |
|
<p class="sidebar-title">Important</p> |
|
<p>This page contains the API reference information. For tutorial |
|
information and discussion of more advanced topics, see</p> |
|
<ul class="simple"> |
|
<li><p><a class="reference internal" href="https://docs.python.org/3/howto/logging.html#logging-basic-tutorial"><span class="std std-ref">Basic Tutorial</span></a></p></li> |
|
<li><p><a class="reference internal" href="https://docs.python.org/3/howto/logging.html#logging-advanced-tutorial"><span class="std std-ref">Advanced Tutorial</span></a></p></li> |
|
<li><p><a class="reference internal" href="https://docs.python.org/3/howto/logging-cookbook.html#logging-cookbook"><span class="std std-ref">Logging Cookbook</span></a></p></li> |
|
</ul> |
|
</aside> |
|
<hr class="docutils"> |
|
<p>This module defines functions and classes which implement a flexible event |
|
logging system for applications and libraries.</p> |
|
<p>The key benefit of having the logging API provided by a standard library module |
|
is that all Python modules can participate in logging, so your application log |
|
can include your own messages integrated with messages from third-party |
|
modules.</p> |
|
<p>The simplest example:</p> |
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>>>> import logging |
|
>>> logging.warning('Watch out!') |
|
WARNING:root:Watch out! |
|
</pre></div> |
|
</div> |
|
<p>The module provides a lot of functionality and flexibility. If you are |
|
unfamiliar with logging, the best way to get to grips with it is to view the |
|
tutorials (<strong>see the links above and on the right</strong>).</p> |
|
<p>The basic classes defined by the module, together with their functions, are |
|
listed below.</p> |
|
<ul class="simple"> |
|
<li><p>Loggers expose the interface that application code directly uses.</p></li> |
|
<li><p>Handlers send the log records (created by loggers) to the appropriate |
|
destination.</p></li> |
|
<li><p>Filters provide a finer grained facility for determining which log records |
|
to output.</p></li> |
|
<li><p>Formatters specify the layout of log records in the final output.</p></li> |
|
</ul> |
|
<section id="logger-objects"> |
|
<span id="logger"></span><h2>Logger Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#logger-objects" title="Permalink to this headline">¶</a></h2> |
|
<p>Loggers have the following attributes and methods. Note that Loggers should |
|
<em>NEVER</em> be instantiated directly, but always through the module-level function |
|
<code class="docutils literal notranslate"><span class="pre">logging.getLogger(name)</span></code>. Multiple calls to <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.getLogger" title="logging.getLogger"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogger()</span></code></a> with the same |
|
name will always return a reference to the same Logger object.</p> |
|
<p>The <code class="docutils literal notranslate"><span class="pre">name</span></code> is potentially a period-separated hierarchical value, like |
|
<code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code> (though it could also be just plain <code class="docutils literal notranslate"><span class="pre">foo</span></code>, for example). |
|
Loggers that are further down in the hierarchical list are children of loggers |
|
higher up in the list. For example, given a logger with a name of <code class="docutils literal notranslate"><span class="pre">foo</span></code>, |
|
loggers with names of <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>, <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>, and <code class="docutils literal notranslate"><span class="pre">foo.bam</span></code> are all |
|
descendants of <code class="docutils literal notranslate"><span class="pre">foo</span></code>. The logger name hierarchy is analogous to the Python |
|
package hierarchy, and identical to it if you organise your loggers on a |
|
per-module basis using the recommended construction |
|
<code class="docutils literal notranslate"><span class="pre">logging.getLogger(__name__)</span></code>. That’s because in a module, <code class="docutils literal notranslate"><span class="pre">__name__</span></code> |
|
is the module’s name in the Python package namespace.</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.Logger"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">Logger</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger" title="Permalink to this definition">¶</a></dt> |
|
<dd><dl class="py attribute"> |
|
<dt class="sig sig-object py" id="logging.Logger.propagate"> |
|
<span class="sig-name descname"><span class="pre">propagate</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.propagate" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>If this attribute evaluates to true, events logged to this logger will be |
|
passed to the handlers of higher level (ancestor) loggers, in addition to |
|
any handlers attached to this logger. Messages are passed directly to the |
|
ancestor loggers’ handlers - neither the level nor filters of the ancestor |
|
loggers in question are considered.</p> |
|
<p>If this evaluates to false, logging messages are not passed to the handlers |
|
of ancestor loggers.</p> |
|
<p>Spelling it out with an example: If the propagate attribute of the logger named |
|
<code class="docutils literal notranslate"><span class="pre">A.B.C</span></code> evaluates to true, any event logged to <code class="docutils literal notranslate"><span class="pre">A.B.C</span></code> via a method call such as |
|
<code class="docutils literal notranslate"><span class="pre">logging.getLogger('A.B.C').error(...)</span></code> will [subject to passing that logger’s |
|
level and filter settings] be passed in turn to any handlers attached to loggers |
|
named <code class="docutils literal notranslate"><span class="pre">A.B</span></code>, <code class="docutils literal notranslate"><span class="pre">A</span></code> and the root logger, after first being passed to any handlers |
|
attached to <code class="docutils literal notranslate"><span class="pre">A.B.C</span></code>. If any logger in the chain <code class="docutils literal notranslate"><span class="pre">A.B.C</span></code>, <code class="docutils literal notranslate"><span class="pre">A.B</span></code>, <code class="docutils literal notranslate"><span class="pre">A</span></code> has its |
|
<code class="docutils literal notranslate"><span class="pre">propagate</span></code> attribute set to false, then that is the last logger whose handlers |
|
are offered the event to handle, and propagation stops at that point.</p> |
|
<p>The constructor sets this attribute to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>If you attach a handler to a logger <em>and</em> one or more of its |
|
ancestors, it may emit the same record multiple times. In general, you |
|
should not need to attach a handler to more than one logger - if you just |
|
attach it to the appropriate logger which is highest in the logger |
|
hierarchy, then it will see all events logged by all descendant loggers, |
|
provided that their propagate setting is left set to <code class="docutils literal notranslate"><span class="pre">True</span></code>. A common |
|
scenario is to attach handlers only to the root logger, and to let |
|
propagation take care of the rest.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.setLevel"> |
|
<span class="sig-name descname"><span class="pre">setLevel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.setLevel" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Sets the threshold for this logger to <em>level</em>. Logging messages which are less |
|
severe than <em>level</em> will be ignored; logging messages which have severity <em>level</em> |
|
or higher will be emitted by whichever handler or handlers service this logger, |
|
unless a handler’s level has been set to a higher severity level than <em>level</em>.</p> |
|
<p>When a logger is created, the level is set to <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.NOTSET" title="logging.NOTSET"><code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code></a> (which causes |
|
all messages to be processed when the logger is the root logger, or delegation |
|
to the parent when the logger is a non-root logger). Note that the root logger |
|
is created with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a>.</p> |
|
<p>The term ‘delegation to the parent’ means that if a logger has a level of |
|
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with |
|
a level other than NOTSET is found, or the root is reached.</p> |
|
<p>If an ancestor is found with a level other than NOTSET, then that ancestor’s |
|
level is treated as the effective level of the logger where the ancestor search |
|
began, and is used to determine how a logging event is handled.</p> |
|
<p>If the root is reached, and it has a level of NOTSET, then all messages will be |
|
processed. Otherwise, the root’s level will be used as the effective level.</p> |
|
<p>See <a class="reference internal" href="https://docs.python.org/3/library/logging.html#levels"><span class="std std-ref">Logging Levels</span></a> for a list of levels.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>level</em> parameter now accepts a string representation of the |
|
level such as ‘INFO’ as an alternative to the integer constants |
|
such as <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a>. Note, however, that levels are internally stored |
|
as integers, and methods such as e.g. <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a> and |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a> will return/expect to be passed integers.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.isEnabledFor"> |
|
<span class="sig-name descname"><span class="pre">isEnabledFor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.isEnabledFor" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Indicates if a message of severity <em>level</em> would be processed by this logger. |
|
This method checks first the module-level level set by |
|
<code class="docutils literal notranslate"><span class="pre">logging.disable(level)</span></code> and then the logger’s effective level as determined |
|
by <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.getEffectiveLevel"> |
|
<span class="sig-name descname"><span class="pre">getEffectiveLevel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.getEffectiveLevel" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Indicates the effective level for this logger. If a value other than |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.NOTSET" title="logging.NOTSET"><code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code></a> has been set using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a>, it is returned. Otherwise, |
|
the hierarchy is traversed towards the root until a value other than |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.NOTSET" title="logging.NOTSET"><code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code></a> is found, and that value is returned. The value returned is |
|
an integer, typically one of <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="logging.DEBUG"><code class="xref py py-const docutils literal notranslate"><span class="pre">logging.DEBUG</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">logging.INFO</span></code></a> |
|
etc.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.getChild"> |
|
<span class="sig-name descname"><span class="pre">getChild</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">suffix</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.getChild" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns a logger which is a descendant to this logger, as determined by the suffix. |
|
Thus, <code class="docutils literal notranslate"><span class="pre">logging.getLogger('abc').getChild('def.ghi')</span></code> would return the same |
|
logger as would be returned by <code class="docutils literal notranslate"><span class="pre">logging.getLogger('abc.def.ghi')</span></code>. This is a |
|
convenience method, useful when the parent logger is named using e.g. <code class="docutils literal notranslate"><span class="pre">__name__</span></code> |
|
rather than a literal string.</p> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.2.</span></p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.debug"> |
|
<span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.debug" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="logging.DEBUG"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code></a> on this logger. The <em>msg</em> is the |
|
message format string, and the <em>args</em> are the arguments which are merged into |
|
<em>msg</em> using the string formatting operator. (Note that this means that you can |
|
use keywords in the format string, together with a single dictionary argument.) |
|
No % formatting operation is performed on <em>msg</em> when no <em>args</em> are supplied.</p> |
|
<p>There are four keyword arguments in <em>kwargs</em> which are inspected: |
|
<em>exc_info</em>, <em>stack_info</em>, <em>stacklevel</em> and <em>extra</em>.</p> |
|
<p>If <em>exc_info</em> does not evaluate as false, it causes exception information to be |
|
added to the logging message. If an exception tuple (in the format returned by |
|
<a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>) or an exception instance is provided, it is used; |
|
otherwise, <a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> is called to get the exception information.</p> |
|
<p>The second optional keyword argument is <em>stack_info</em>, which defaults to |
|
<code class="docutils literal notranslate"><span class="pre">False</span></code>. If true, stack information is added to the logging |
|
message, including the actual logging call. Note that this is not the same |
|
stack information as that displayed through specifying <em>exc_info</em>: The |
|
former is stack frames from the bottom of the stack up to the logging call |
|
in the current thread, whereas the latter is information about stack frames |
|
which have been unwound, following an exception, while searching for |
|
exception handlers.</p> |
|
<p>You can specify <em>stack_info</em> independently of <em>exc_info</em>, e.g. to just show |
|
how you got to a certain point in your code, even when no exceptions were |
|
raised. The stack frames are printed following a header line which says:</p> |
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Stack (most recent call last): |
|
</pre></div> |
|
</div> |
|
<p>This mimics the <code class="docutils literal notranslate"><span class="pre">Traceback</span> <span class="pre">(most</span> <span class="pre">recent</span> <span class="pre">call</span> <span class="pre">last):</span></code> which is used when |
|
displaying exception frames.</p> |
|
<p>The third optional keyword argument is <em>stacklevel</em>, which defaults to <code class="docutils literal notranslate"><span class="pre">1</span></code>. |
|
If greater than 1, the corresponding number of stack frames are skipped |
|
when computing the line number and function name set in the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> |
|
created for the logging event. This can be used in logging helpers so that |
|
the function name, filename and line number recorded are not the information |
|
for the helper function/method, but rather its caller. The name of this |
|
parameter mirrors the equivalent one in the <a class="reference internal" href="https://docs.python.org/3/library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module.</p> |
|
<p>The fourth keyword argument is <em>extra</em> which can be used to pass a |
|
dictionary which is used to populate the __dict__ of the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> |
|
created for the logging event with user-defined attributes. These custom |
|
attributes can then be used as you like. For example, they could be |
|
incorporated into logged messages. For example:</p> |
|
<div class="highlight-python3 notranslate"><div class="highlight" style="position: relative;"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(clientip)-15s</span><span class="s1"> </span><span class="si">%(user)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span> |
|
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="n">FORMAT</span><span class="p">)</span> |
|
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'clientip'</span><span class="p">:</span> <span class="s1">'192.168.0.1'</span><span class="p">,</span> <span class="s1">'user'</span><span class="p">:</span> <span class="s1">'fbloggs'</span><span class="p">}</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">'tcpserver'</span><span class="p">)</span> |
|
<span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s1">'Protocol problem: </span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="s1">'connection reset'</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">d</span><span class="p">)</span> |
|
</pre></div> |
|
</div> |
|
<p>would print something like</p> |
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset |
|
</pre></div> |
|
</div> |
|
<p>The keys in the dictionary passed in <em>extra</em> should not clash with the keys used |
|
by the logging system. (See the section on <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-attributes"><span class="std std-ref">LogRecord attributes</span></a> for more |
|
information on which keys are used by the logging system.)</p> |
|
<p>If you choose to use these attributes in logged messages, you need to exercise |
|
some care. In the above example, for instance, the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> has been |
|
set up with a format string which expects ‘clientip’ and ‘user’ in the attribute |
|
dictionary of the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>. If these are missing, the message will |
|
not be logged because a string formatting exception will occur. So in this case, |
|
you always need to pass the <em>extra</em> dictionary with these keys.</p> |
|
<p>While this might be annoying, this feature is intended for use in specialized |
|
circumstances, such as multi-threaded servers where the same code executes in |
|
many contexts, and interesting conditions which arise are dependent on this |
|
context (such as remote client IP address and authenticated user name, in the |
|
above example). In such circumstances, it is likely that specialized |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a>s would be used with particular <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a>s.</p> |
|
<p>If no handler is attached to this logger (or any of its ancestors, |
|
taking into account the relevant <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.propagate" title="logging.Logger.propagate"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Logger.propagate</span></code></a> attributes), |
|
the message will be sent to the handler set on <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.lastResort" title="logging.lastResort"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lastResort</span></code></a>.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>stack_info</em> parameter was added.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>exc_info</em> parameter can now accept exception instances.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>stacklevel</em> parameter was added.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.info"> |
|
<span class="sig-name descname"><span class="pre">info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.info" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a> on this logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.warning"> |
|
<span class="sig-name descname"><span class="pre">warning</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.warning" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a> on this logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>There is an obsolete method <code class="docutils literal notranslate"><span class="pre">warn</span></code> which is functionally |
|
identical to <code class="docutils literal notranslate"><span class="pre">warning</span></code>. As <code class="docutils literal notranslate"><span class="pre">warn</span></code> is deprecated, please do not use |
|
it - use <code class="docutils literal notranslate"><span class="pre">warning</span></code> instead.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.error"> |
|
<span class="sig-name descname"><span class="pre">error</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.error" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a> on this logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.critical"> |
|
<span class="sig-name descname"><span class="pre">critical</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.critical" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="logging.CRITICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code></a> on this logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.log"> |
|
<span class="sig-name descname"><span class="pre">log</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.log" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with integer level <em>level</em> on this logger. The other arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.exception"> |
|
<span class="sig-name descname"><span class="pre">exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.exception" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a> on this logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a>. Exception info is added to the logging |
|
message. This method should only be called from an exception handler.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.addFilter"> |
|
<span class="sig-name descname"><span class="pre">addFilter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filter</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.addFilter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Adds the specified filter <em>filter</em> to this logger.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.removeFilter"> |
|
<span class="sig-name descname"><span class="pre">removeFilter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filter</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.removeFilter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Removes the specified filter <em>filter</em> from this logger.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.filter"> |
|
<span class="sig-name descname"><span class="pre">filter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.filter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Apply this logger’s filters to the record and return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the |
|
record is to be processed. The filters are consulted in turn, until one of |
|
them returns a false value. If none of them return a false value, the record |
|
will be processed (passed to handlers). If one returns a false value, no |
|
further processing of the record occurs.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.addHandler"> |
|
<span class="sig-name descname"><span class="pre">addHandler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hdlr</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.addHandler" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Adds the specified handler <em>hdlr</em> to this logger.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.removeHandler"> |
|
<span class="sig-name descname"><span class="pre">removeHandler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hdlr</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.removeHandler" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Removes the specified handler <em>hdlr</em> from this logger.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.findCaller"> |
|
<span class="sig-name descname"><span class="pre">findCaller</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack_info</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stacklevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.findCaller" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Finds the caller’s source filename and line number. Returns the filename, line |
|
number, function name and stack information as a 4-element tuple. The stack |
|
information is returned as <code class="docutils literal notranslate"><span class="pre">None</span></code> unless <em>stack_info</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p> |
|
<p>The <em>stacklevel</em> parameter is passed from code calling the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a> |
|
and other APIs. If greater than 1, the excess is used to skip stack frames |
|
before determining the values to be returned. This will generally be useful |
|
when calling logging APIs from helper/wrapper code, so that the information |
|
in the event log refers not to the helper/wrapper code, but to the code that |
|
calls it.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.handle"> |
|
<span class="sig-name descname"><span class="pre">handle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.handle" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Handles a record by passing it to all handlers associated with this logger and |
|
its ancestors (until a false value of <em>propagate</em> is found). This method is used |
|
for unpickled records received from a socket, as well as those created locally. |
|
Logger-level filtering is applied using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.filter" title="logging.Logger.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.makeRecord"> |
|
<span class="sig-name descname"><span class="pre">makeRecord</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fn</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lno</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_info</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extra</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.makeRecord" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This is a factory method which can be overridden in subclasses to create |
|
specialized <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> instances.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Logger.hasHandlers"> |
|
<span class="sig-name descname"><span class="pre">hasHandlers</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Logger.hasHandlers" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Checks to see if this logger has any handlers configured. This is done by |
|
looking for handlers in this logger and its parents in the logger hierarchy. |
|
Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if a handler was found, else <code class="docutils literal notranslate"><span class="pre">False</span></code>. The method stops searching |
|
up the hierarchy whenever a logger with the ‘propagate’ attribute set to |
|
false is found - that will be the last logger which is checked for the |
|
existence of handlers.</p> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.2.</span></p> |
|
</div> |
|
</dd></dl> |
|
|
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>Loggers can now be pickled and unpickled.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
</section> |
|
<section id="logging-levels"> |
|
<span id="levels"></span><h2>Logging Levels<a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging-levels" title="Permalink to this headline">¶</a></h2> |
|
<p>The numeric values of logging levels are given in the following table. These are |
|
primarily of interest if you want to define your own levels, and need them to |
|
have specific values relative to the predefined levels. If you define a level |
|
with the same numeric value, it overwrites the predefined value; the predefined |
|
name is lost.</p> |
|
<div class="responsive-table__container"><table class="docutils align-default"> |
|
<colgroup> |
|
<col style="width: 31%"> |
|
<col style="width: 20%"> |
|
<col style="width: 49%"> |
|
</colgroup> |
|
<thead> |
|
<tr class="row-odd"><th class="head"><p>Level</p></th> |
|
<th class="head"><p>Numeric value</p></th> |
|
<th class="head"><p>What it means / When to use it</p></th> |
|
</tr> |
|
</thead> |
|
<tbody> |
|
<tr class="row-even"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.NOTSET"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">NOTSET</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.NOTSET" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>0</p></td> |
|
<td><p>When set on a logger, indicates that |
|
ancestor loggers are to be consulted |
|
to determine the effective level. |
|
If that still resolves to |
|
<code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code>, then all events |
|
are logged. When set on a handler, |
|
all events are handled.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.DEBUG"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">DEBUG</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>10</p></td> |
|
<td><p>Detailed information, typically only |
|
of interest to a developer trying to |
|
diagnose a problem.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.INFO"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">INFO</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>20</p></td> |
|
<td><p>Confirmation that things are working |
|
as expected.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.WARNING"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">WARNING</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>30</p></td> |
|
<td><p>An indication that something |
|
unexpected happened, or that a |
|
problem might occur in the near |
|
future (e.g. ‘disk space low’). The |
|
software is still working as |
|
expected.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.ERROR"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">ERROR</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>40</p></td> |
|
<td><p>Due to a more serious problem, the |
|
software has not been able to |
|
perform some function.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><dl class="py data"> |
|
<dt class="sig sig-object py" id="logging.CRITICAL"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">CRITICAL</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="Permalink to this definition">¶</a></dt> |
|
<dd></dd></dl> |
|
|
|
</td> |
|
<td><p>50</p></td> |
|
<td><p>A serious error, indicating that the |
|
program itself may be unable to |
|
continue running.</p></td> |
|
</tr> |
|
</tbody> |
|
</table></div> |
|
</section> |
|
<section id="handler-objects"> |
|
<span id="handler"></span><h2>Handler Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#handler-objects" title="Permalink to this headline">¶</a></h2> |
|
<p>Handlers have the following attributes and methods. Note that <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> |
|
is never instantiated directly; this class acts as a base for more useful |
|
subclasses. However, the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> method in subclasses needs to call |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.__init__" title="logging.Handler.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Handler.__init__()</span></code></a>.</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.Handler"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">Handler</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler" title="Permalink to this definition">¶</a></dt> |
|
<dd><dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.__init__"> |
|
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">NOTSET</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.__init__" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Initializes the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a> instance by setting its level, setting the list |
|
of filters to the empty list and creating a lock (using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">createLock()</span></code></a>) for |
|
serializing access to an I/O mechanism.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.createLock"> |
|
<span class="sig-name descname"><span class="pre">createLock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.createLock" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Initializes a thread lock which can be used to serialize access to underlying |
|
I/O functionality which may not be threadsafe.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.acquire"> |
|
<span class="sig-name descname"><span class="pre">acquire</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.acquire" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Acquires the thread lock created with <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.createLock" title="logging.Handler.createLock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">createLock()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.release"> |
|
<span class="sig-name descname"><span class="pre">release</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.release" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Releases the thread lock acquired with <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.acquire" title="logging.Handler.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.setLevel"> |
|
<span class="sig-name descname"><span class="pre">setLevel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.setLevel" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Sets the threshold for this handler to <em>level</em>. Logging messages which are |
|
less severe than <em>level</em> will be ignored. When a handler is created, the |
|
level is set to <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.NOTSET" title="logging.NOTSET"><code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code></a> (which causes all messages to be |
|
processed).</p> |
|
<p>See <a class="reference internal" href="https://docs.python.org/3/library/logging.html#levels"><span class="std std-ref">Logging Levels</span></a> for a list of levels.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>level</em> parameter now accepts a string representation of the |
|
level such as ‘INFO’ as an alternative to the integer constants |
|
such as <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.setFormatter"> |
|
<span class="sig-name descname"><span class="pre">setFormatter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fmt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.setFormatter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Sets the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> for this handler to <em>fmt</em>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.addFilter"> |
|
<span class="sig-name descname"><span class="pre">addFilter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filter</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.addFilter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Adds the specified filter <em>filter</em> to this handler.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.removeFilter"> |
|
<span class="sig-name descname"><span class="pre">removeFilter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filter</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.removeFilter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Removes the specified filter <em>filter</em> from this handler.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.filter"> |
|
<span class="sig-name descname"><span class="pre">filter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.filter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Apply this handler’s filters to the record and return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the |
|
record is to be processed. The filters are consulted in turn, until one of |
|
them returns a false value. If none of them return a false value, the record |
|
will be emitted. If one returns a false value, the handler will not emit the |
|
record.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.flush"> |
|
<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.flush" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Ensure all logging output has been flushed. This version does nothing and is |
|
intended to be implemented by subclasses.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.close"> |
|
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.close" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Tidy up any resources used by the handler. This version does no output but |
|
removes the handler from an internal list of handlers which is closed when |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.shutdown" title="logging.shutdown"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutdown()</span></code></a> is called. Subclasses should ensure that this gets called |
|
from overridden <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.close" title="logging.Handler.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> methods.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.handle"> |
|
<span class="sig-name descname"><span class="pre">handle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.handle" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Conditionally emits the specified logging record, depending on filters which may |
|
have been added to the handler. Wraps the actual emission of the record with |
|
acquisition/release of the I/O thread lock.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.handleError"> |
|
<span class="sig-name descname"><span class="pre">handleError</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.handleError" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This method should be called from handlers when an exception is encountered |
|
during an <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler.emit" title="logging.Handler.emit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">emit()</span></code></a> call. If the module-level attribute |
|
<code class="docutils literal notranslate"><span class="pre">raiseExceptions</span></code> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, exceptions get silently ignored. This is |
|
what is mostly wanted for a logging system - most users will not care about |
|
errors in the logging system, they are more interested in application |
|
errors. You could, however, replace this with a custom handler if you wish. |
|
The specified record is the one which was being processed when the exception |
|
occurred. (The default value of <code class="docutils literal notranslate"><span class="pre">raiseExceptions</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, as that is |
|
more useful during development).</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.format"> |
|
<span class="sig-name descname"><span class="pre">format</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.format" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Do formatting for a record - if a formatter is set, use it. Otherwise, use the |
|
default formatter for the module.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Handler.emit"> |
|
<span class="sig-name descname"><span class="pre">emit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Handler.emit" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Do whatever it takes to actually log the specified logging record. This version |
|
is intended to be implemented by subclasses and so raises a |
|
<a class="reference internal" href="https://docs.python.org/3/library/exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p> |
|
<div class="admonition warning"> |
|
<p class="admonition-title">Warning</p> |
|
<p>This method is called after a handler-level lock is acquired, which |
|
is released after this method returns. When you override this method, note |
|
that you should be careful when calling anything that invokes other parts of |
|
the logging API which might do locking, because that might result in a |
|
deadlock. Specifically:</p> |
|
<ul class="simple"> |
|
<li><p>Logging configuration APIs acquire the module-level lock, and then |
|
individual handler-level locks as those handlers are configured.</p></li> |
|
<li><p>Many logging APIs lock the module-level lock. If such an API is called |
|
from this method, it could cause a deadlock if a configuration call is |
|
made on another thread, because that thread will try to acquire the |
|
module-level lock <em>before</em> the handler-level lock, whereas this thread |
|
tries to acquire the module-level lock <em>after</em> the handler-level lock |
|
(because in this method, the handler-level lock has already been acquired).</p></li> |
|
</ul> |
|
</div> |
|
</dd></dl> |
|
|
|
</dd></dl> |
|
|
|
<p>For a list of handlers included as standard, see <a class="reference internal" href="https://docs.python.org/3/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>.</p> |
|
</section> |
|
<section id="formatter-objects"> |
|
<span id="id1"></span><h2>Formatter Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#formatter-objects" title="Permalink to this headline">¶</a></h2> |
|
<p><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> objects have the following attributes and methods. They are |
|
responsible for converting a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> to (usually) a string which can |
|
be interpreted by either a human or an external system. The base |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> allows a formatting string to be specified. If none is |
|
supplied, the default value of <code class="docutils literal notranslate"><span class="pre">'%(message)s'</span></code> is used, which just includes |
|
the message in the logging call. To have additional items of information in the |
|
formatted output (such as a timestamp), keep reading.</p> |
|
<p>A Formatter can be initialized with a format string which makes use of knowledge |
|
of the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> attributes - such as the default value mentioned above |
|
making use of the fact that the user’s message and arguments are pre-formatted |
|
into a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>’s <em>message</em> attribute. This format string contains |
|
standard Python %-style mapping keys. See section <a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#old-string-formatting"><span class="std std-ref">printf-style String Formatting</span></a> |
|
for more information on string formatting.</p> |
|
<p>The useful mapping keys in a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> are given in the section on |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-attributes"><span class="std std-ref">LogRecord attributes</span></a>.</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.Formatter"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">Formatter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fmt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">datefmt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">style</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'%'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">validate</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">defaults</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns a new instance of the <a class="reference internal" href="https://docs.python.org/3/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. The instance is |
|
initialized with a format string for the message as a whole, as well as a |
|
format string for the date/time portion of a message. If no <em>fmt</em> is |
|
specified, <code class="docutils literal notranslate"><span class="pre">'%(message)s'</span></code> is used. If no <em>datefmt</em> is specified, a format |
|
is used which is described in the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatTime" title="logging.Formatter.formatTime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatTime()</span></code></a> documentation.</p> |
|
<p>The <em>style</em> parameter can be one of ‘%’, ‘{’ or ‘$’ and determines how |
|
the format string will be merged with its data: using one of %-formatting, |
|
<a class="reference internal" href="https://docs.python.org/3/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="https://docs.python.org/3/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>. This only applies to the |
|
format string <em>fmt</em> (e.g. <code class="docutils literal notranslate"><span class="pre">'%(message)s'</span></code> or <code class="docutils literal notranslate"><span class="pre">{message}</span></code>), not to the |
|
actual log messages passed to <code class="docutils literal notranslate"><span class="pre">Logger.debug</span></code> etc; see |
|
<a class="reference internal" href="https://docs.python.org/3/howto/logging-cookbook.html#formatting-styles"><span class="std std-ref">Using particular formatting styles throughout your application</span></a> for more information on using {- and $-formatting |
|
for log messages.</p> |
|
<p>The <em>defaults</em> parameter can be a dictionary with default values to use in |
|
custom fields. For example: |
|
<code class="docutils literal notranslate"><span class="pre">logging.Formatter('%(ip)s</span> <span class="pre">%(message)s',</span> <span class="pre">defaults={"ip":</span> <span class="pre">None})</span></code></p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>style</em> parameter was added.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>validate</em> parameter was added. Incorrect or mismatched style and fmt |
|
will raise a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>. |
|
For example: <code class="docutils literal notranslate"><span class="pre">logging.Formatter('%(asctime)s</span> <span class="pre">-</span> <span class="pre">%(message)s',</span> <span class="pre">style='{')</span></code>.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.10: </span>The <em>defaults</em> parameter was added.</p> |
|
</div> |
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Formatter.format"> |
|
<span class="sig-name descname"><span class="pre">format</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Formatter.format" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>The record’s attribute dictionary is used as the operand to a string |
|
formatting operation. Returns the resulting string. Before formatting the |
|
dictionary, a couple of preparatory steps are carried out. The <em>message</em> |
|
attribute of the record is computed using <em>msg</em> % <em>args</em>. If the |
|
formatting string contains <code class="docutils literal notranslate"><span class="pre">'(asctime)'</span></code>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatTime" title="logging.Formatter.formatTime"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatTime()</span></code></a> is called |
|
to format the event time. If there is exception information, it is |
|
formatted using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatException" title="logging.Formatter.formatException"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatException()</span></code></a> and appended to the message. Note |
|
that the formatted exception information is cached in attribute |
|
<em>exc_text</em>. This is useful because the exception information can be |
|
pickled and sent across the wire, but you should be careful if you have |
|
more than one <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> subclass which customizes the formatting |
|
of exception information. In this case, you will have to clear the cached |
|
value (by setting the <em>exc_text</em> attribute to <code class="docutils literal notranslate"><span class="pre">None</span></code>) after a formatter |
|
has done its formatting, so that the next formatter to handle the event |
|
doesn’t use the cached value, but recalculates it afresh.</p> |
|
<p>If stack information is available, it’s appended after the exception |
|
information, using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatStack" title="logging.Formatter.formatStack"><code class="xref py py-meth docutils literal notranslate"><span class="pre">formatStack()</span></code></a> to transform it if necessary.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Formatter.formatTime"> |
|
<span class="sig-name descname"><span class="pre">formatTime</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">datefmt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatTime" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This method should be called from <a class="reference internal" href="https://docs.python.org/3/library/functions.html#format" title="format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">format()</span></code></a> by a formatter which |
|
wants to make use of a formatted time. This method can be overridden in |
|
formatters to provide for any specific requirement, but the basic behavior |
|
is as follows: if <em>datefmt</em> (a string) is specified, it is used with |
|
<a class="reference internal" href="https://docs.python.org/3/library/time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a> to format the creation time of the |
|
record. Otherwise, the format ‘%Y-%m-%d %H:%M:%S,uuu’ is used, where the |
|
uuu part is a millisecond value and the other letters are as per the |
|
<a class="reference internal" href="https://docs.python.org/3/library/time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a> documentation. An example time in this format is |
|
<code class="docutils literal notranslate"><span class="pre">2003-01-23</span> <span class="pre">00:29:50,411</span></code>. The resulting string is returned.</p> |
|
<p>This function uses a user-configurable function to convert the creation |
|
time to a tuple. By default, <a class="reference internal" href="https://docs.python.org/3/library/time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a> is used; to change |
|
this for a particular formatter instance, set the <code class="docutils literal notranslate"><span class="pre">converter</span></code> attribute |
|
to a function with the same signature as <a class="reference internal" href="https://docs.python.org/3/library/time.html#time.localtime" title="time.localtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.localtime()</span></code></a> or |
|
<a class="reference internal" href="https://docs.python.org/3/library/time.html#time.gmtime" title="time.gmtime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.gmtime()</span></code></a>. To change it for all formatters, for example if you |
|
want all logging times to be shown in GMT, set the <code class="docutils literal notranslate"><span class="pre">converter</span></code> |
|
attribute in the <code class="docutils literal notranslate"><span class="pre">Formatter</span></code> class.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>Previously, the default format was hard-coded as in this example: |
|
<code class="docutils literal notranslate"><span class="pre">2010-09-06</span> <span class="pre">22:38:15,292</span></code> where the part before the comma is |
|
handled by a strptime format string (<code class="docutils literal notranslate"><span class="pre">'%Y-%m-%d</span> <span class="pre">%H:%M:%S'</span></code>), and the |
|
part after the comma is a millisecond value. Because strptime does not |
|
have a format placeholder for milliseconds, the millisecond value is |
|
appended using another format string, <code class="docutils literal notranslate"><span class="pre">'%s,%03d'</span></code> — and both of these |
|
format strings have been hardcoded into this method. With the change, |
|
these strings are defined as class-level attributes which can be |
|
overridden at the instance level when desired. The names of the |
|
attributes are <code class="docutils literal notranslate"><span class="pre">default_time_format</span></code> (for the strptime format string) |
|
and <code class="docutils literal notranslate"><span class="pre">default_msec_format</span></code> (for appending the millisecond value).</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.9: </span>The <code class="docutils literal notranslate"><span class="pre">default_msec_format</span></code> can be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Formatter.formatException"> |
|
<span class="sig-name descname"><span class="pre">formatException</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exc_info</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatException" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Formats the specified exception information (a standard exception tuple as |
|
returned by <a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>) as a string. This default implementation |
|
just uses <a class="reference internal" href="https://docs.python.org/3/library/traceback.html#traceback.print_exception" title="traceback.print_exception"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_exception()</span></code></a>. The resulting string is |
|
returned.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Formatter.formatStack"> |
|
<span class="sig-name descname"><span class="pre">formatStack</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stack_info</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Formatter.formatStack" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Formats the specified stack information (a string as returned by |
|
<a class="reference internal" href="https://docs.python.org/3/library/traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_stack()</span></code></a>, but with the last newline removed) as a |
|
string. This default implementation just returns the input value.</p> |
|
</dd></dl> |
|
|
|
</dd></dl> |
|
|
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.BufferingFormatter"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">BufferingFormatter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">linefmt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.BufferingFormatter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>A base formatter class suitable for subclassing when you want to format a |
|
number of records. You can pass a <a class="reference internal" href="https://docs.python.org/3/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 which you want |
|
to use to format each line (that corresponds to a single record). If not |
|
specified, the default formatter (which just outputs the event message) is |
|
used as the line formatter.</p> |
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.BufferingFormatter.formatHeader"> |
|
<span class="sig-name descname"><span class="pre">formatHeader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">records</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.BufferingFormatter.formatHeader" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return a header for a list of <em>records</em>. The base implementation just |
|
returns the empty string. You will need to override this method if you |
|
want specific behaviour, e.g. to show the count of records, a title or a |
|
separator line.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.BufferingFormatter.formatFooter"> |
|
<span class="sig-name descname"><span class="pre">formatFooter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">records</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.BufferingFormatter.formatFooter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return a footer for a list of <em>records</em>. The base implementation just |
|
returns the empty string. You will need to override this method if you |
|
want specific behaviour, e.g. to show the count of records or a separator |
|
line.</p> |
|
</dd></dl> |
|
|
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.BufferingFormatter.format"> |
|
<span class="sig-name descname"><span class="pre">format</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">records</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.BufferingFormatter.format" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return formatted text for a list of <em>records</em>. The base implementation |
|
just returns the empty string if there are no records; otherwise, it |
|
returns the concatenation of the header, each record formatted with the |
|
line formatter, and the footer.</p> |
|
</dd></dl> |
|
|
|
</dd></dl> |
|
|
|
</section> |
|
<section id="filter-objects"> |
|
<span id="filter"></span><h2>Filter Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#filter-objects" title="Permalink to this headline">¶</a></h2> |
|
<p><code class="docutils literal notranslate"><span class="pre">Filters</span></code> can be used by <code class="docutils literal notranslate"><span class="pre">Handlers</span></code> and <code class="docutils literal notranslate"><span class="pre">Loggers</span></code> for more sophisticated |
|
filtering than is provided by levels. The base filter class only allows events |
|
which are below a certain point in the logger hierarchy. For example, a filter |
|
initialized with ‘A.B’ will allow events logged by loggers ‘A.B’, ‘A.B.C’, |
|
‘A.B.C.D’, ‘A.B.D’ etc. but not ‘A.BB’, ‘B.A.B’ etc. If initialized with the |
|
empty string, all events are passed.</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.Filter"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">Filter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Filter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns an instance of the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> class. If <em>name</em> is specified, it |
|
names a logger which, together with its children, will have its events allowed |
|
through the filter. If <em>name</em> is the empty string, allows every event.</p> |
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.Filter.filter"> |
|
<span class="sig-name descname"><span class="pre">filter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">record</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.Filter.filter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Is the specified record to be logged? Returns zero for no, nonzero for |
|
yes. If deemed appropriate, the record may be modified in-place by this |
|
method.</p> |
|
</dd></dl> |
|
|
|
</dd></dl> |
|
|
|
<p>Note that filters attached to handlers are consulted before an event is |
|
emitted by the handler, whereas filters attached to loggers are consulted |
|
whenever an event is logged (using <a class="reference internal" href="https://docs.python.org/3/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="https://docs.python.org/3/library/logging.html#logging.info" title="logging.info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code></a>, |
|
etc.), before sending an event to handlers. This means that events which have |
|
been generated by descendant loggers will not be filtered by a logger’s filter |
|
setting, unless the filter has also been applied to those descendant loggers.</p> |
|
<p>You don’t actually need to subclass <code class="docutils literal notranslate"><span class="pre">Filter</span></code>: you can pass any instance |
|
which has a <code class="docutils literal notranslate"><span class="pre">filter</span></code> method with the same semantics.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>You don’t need to create specialized <code class="docutils literal notranslate"><span class="pre">Filter</span></code> classes, or use other |
|
classes with a <code class="docutils literal notranslate"><span class="pre">filter</span></code> method: you can use a function (or other |
|
callable) as a filter. The filtering logic will check to see if the filter |
|
object has a <code class="docutils literal notranslate"><span class="pre">filter</span></code> attribute: if it does, it’s assumed to be a |
|
<code class="docutils literal notranslate"><span class="pre">Filter</span></code> and its <a class="reference internal" href="https://docs.python.org/3/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. Otherwise, it’s |
|
assumed to be a callable and called with the record as the single |
|
parameter. The returned value should conform to that returned by |
|
<a class="reference internal" href="https://docs.python.org/3/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>.</p> |
|
</div> |
|
<p>Although filters are used primarily to filter records based on more |
|
sophisticated criteria than levels, they get to see every record which is |
|
processed by the handler or logger they’re attached to: this can be useful if |
|
you want to do things like counting how many records were processed by a |
|
particular logger or handler, or adding, changing or removing attributes in |
|
the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> being processed. Obviously changing the LogRecord needs |
|
to be done with some care, but it does allow the injection of contextual |
|
information into logs (see <a class="reference internal" href="https://docs.python.org/3/howto/logging-cookbook.html#filters-contextual"><span class="std std-ref">Using Filters to impart contextual information</span></a>).</p> |
|
</section> |
|
<section id="logrecord-objects"> |
|
<span id="log-record"></span><h2>LogRecord Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#logrecord-objects" title="Permalink to this headline">¶</a></h2> |
|
<p><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> instances are created automatically by the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> |
|
every time something is logged, and can be created manually via |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.makeLogRecord" title="logging.makeLogRecord"><code class="xref py py-func docutils literal notranslate"><span class="pre">makeLogRecord()</span></code></a> (for example, from a pickled event received over the |
|
wire).</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.LogRecord"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">LogRecord</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pathname</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_info</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Contains all the information pertinent to the event being logged.</p> |
|
<p>The primary information is passed in <em>msg</em> and <em>args</em>, |
|
which are combined using <code class="docutils literal notranslate"><span class="pre">msg</span> <span class="pre">%</span> <span class="pre">args</span></code> to create |
|
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">message</span></code> attribute of the record.</p> |
|
<dl class="field-list simple"> |
|
<dt class="field-odd">Parameters</dt> |
|
<dd class="field-odd"><ul class="simple"> |
|
<li><p><strong>name</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><em>str</em></a>) – The name of the logger used to log the event |
|
represented by this <code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code>. |
|
Note that the logger name in the <code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code> |
|
will always have this value, |
|
even though it may be emitted by a handler |
|
attached to a different (ancestor) logger.</p></li> |
|
<li><p><strong>level</strong> (<a class="reference internal" href="https://docs.python.org/3/library/functions.html#int" title="int"><em>int</em></a>) – The <a class="reference internal" href="https://docs.python.org/3/library/logging.html#levels"><span class="std std-ref">numeric level</span></a> of the logging event |
|
(such as <code class="docutils literal notranslate"><span class="pre">10</span></code> for <code class="docutils literal notranslate"><span class="pre">DEBUG</span></code>, <code class="docutils literal notranslate"><span class="pre">20</span></code> for <code class="docutils literal notranslate"><span class="pre">INFO</span></code>, etc). |
|
Note that this is converted to <em>two</em> attributes of the LogRecord: |
|
<code class="xref py py-attr docutils literal notranslate"><span class="pre">levelno</span></code> for the numeric value |
|
and <code class="xref py py-attr docutils literal notranslate"><span class="pre">levelname</span></code> for the corresponding level name.</p></li> |
|
<li><p><strong>pathname</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><em>str</em></a>) – The full string path of the source file |
|
where the logging call was made.</p></li> |
|
<li><p><strong>lineno</strong> (<a class="reference internal" href="https://docs.python.org/3/library/functions.html#int" title="int"><em>int</em></a>) – The line number in the source file |
|
where the logging call was made.</p></li> |
|
<li><p><strong>msg</strong> (<a class="reference internal" href="https://docs.python.org/3/library/typing.html#typing.Any" title="typing.Any"><em>Any</em></a>) – The event description message, |
|
which can be a %-format string with placeholders for variable data, |
|
or an arbitrary object (see <a class="reference internal" href="https://docs.python.org/3/howto/logging.html#arbitrary-object-messages"><span class="std std-ref">Using arbitrary objects as messages</span></a>).</p></li> |
|
<li><p><strong>args</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="tuple"><em>tuple</em></a><em> | </em><a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#dict" title="dict"><em>dict</em></a><em>[</em><a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><em>str</em></a><em>, </em><a class="reference internal" href="https://docs.python.org/3/library/typing.html#typing.Any" title="typing.Any"><em>Any</em></a><em>]</em>) – Variable data to merge into the <em>msg</em> argument |
|
to obtain the event description.</p></li> |
|
<li><p><strong>exc_info</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="tuple"><em>tuple</em></a><em>[</em><a class="reference internal" href="https://docs.python.org/3/library/functions.html#type" title="type"><em>type</em></a><em>[</em><a class="reference internal" href="https://docs.python.org/3/library/exceptions.html#BaseException" title="BaseException"><em>BaseException</em></a><em>]</em><em>, </em><a class="reference internal" href="https://docs.python.org/3/library/exceptions.html#BaseException" title="BaseException"><em>BaseException</em></a><em>, </em><a class="reference internal" href="https://docs.python.org/3/library/types.html#types.TracebackType" title="types.TracebackType"><em>types.TracebackType</em></a><em>] </em><em>| </em><em>None</em>) – An exception tuple with the current exception information, |
|
as returned by <a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>, |
|
or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no exception information is available.</p></li> |
|
<li><p><strong>func</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><em>str</em></a><em> | </em><em>None</em>) – The name of the function or method |
|
from which the logging call was invoked.</p></li> |
|
<li><p><strong>sinfo</strong> (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><em>str</em></a><em> | </em><em>None</em>) – A text string representing stack information |
|
from the base of the stack in the current thread, |
|
up to the logging call.</p></li> |
|
</ul> |
|
</dd> |
|
</dl> |
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.LogRecord.getMessage"> |
|
<span class="sig-name descname"><span class="pre">getMessage</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LogRecord.getMessage" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns the message for this <a class="reference internal" href="https://docs.python.org/3/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 after merging any |
|
user-supplied arguments with the message. If the user-supplied message |
|
argument to the logging call is not a string, <a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> is called on it to |
|
convert it to a string. This allows use of user-defined classes as |
|
messages, whose <code class="docutils literal notranslate"><span class="pre">__str__</span></code> method can return the actual format string to |
|
be used.</p> |
|
</dd></dl> |
|
|
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The creation of a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> has been made more configurable by |
|
providing a factory which is used to create the record. The factory can be |
|
set using <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogRecordFactory()</span></code></a> and <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> |
|
(see this for the factory’s signature).</p> |
|
</div> |
|
<p>This functionality can be used to inject your own values into a |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> at creation time. You can use the following pattern:</p> |
|
<div class="highlight-python3 notranslate"><div class="highlight" style="position: relative;"><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> |
|
|
|
<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> |
|
<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> |
|
<span class="n">record</span><span class="o">.</span><span class="n">custom_attribute</span> <span class="o">=</span> <span class="mh">0xdecafbad</span> |
|
<span class="k">return</span> <span class="n">record</span> |
|
|
|
<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> |
|
</pre></div> |
|
</div> |
|
<p>With this pattern, multiple factories could be chained, and as long |
|
as they don’t overwrite each other’s attributes or unintentionally |
|
overwrite the standard attributes listed above, there should be no |
|
surprises.</p> |
|
</dd></dl> |
|
|
|
</section> |
|
<section id="logrecord-attributes"> |
|
<span id="id2"></span><h2>LogRecord attributes<a class="headerlink" href="https://docs.python.org/3/library/logging.html#logrecord-attributes" title="Permalink to this headline">¶</a></h2> |
|
<p>The LogRecord has a number of attributes, most of which are derived from the |
|
parameters to the constructor. (Note that the names do not always correspond |
|
exactly between the LogRecord constructor parameters and the LogRecord |
|
attributes.) These attributes can be used to merge data from the record into |
|
the format string. The following table lists (in alphabetical order) the |
|
attribute names, their meanings and the corresponding placeholder in a %-style |
|
format string.</p> |
|
<p>If you are using {}-formatting (<a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#str.format" title="str.format"><code class="xref py py-func docutils literal notranslate"><span class="pre">str.format()</span></code></a>), you can use |
|
<code class="docutils literal notranslate"><span class="pre">{attrname}</span></code> as the placeholder in the format string. If you are using |
|
$-formatting (<a class="reference internal" href="https://docs.python.org/3/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>), use the form <code class="docutils literal notranslate"><span class="pre">${attrname}</span></code>. In |
|
both cases, of course, replace <code class="docutils literal notranslate"><span class="pre">attrname</span></code> with the actual attribute name |
|
you want to use.</p> |
|
<p>In the case of {}-formatting, you can specify formatting flags by placing them |
|
after the attribute name, separated from it with a colon. For example: a |
|
placeholder of <code class="docutils literal notranslate"><span class="pre">{msecs:03d}</span></code> would format a millisecond value of <code class="docutils literal notranslate"><span class="pre">4</span></code> as |
|
<code class="docutils literal notranslate"><span class="pre">004</span></code>. Refer to the <a class="reference internal" href="https://docs.python.org/3/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> documentation for full details on |
|
the options available to you.</p> |
|
<div class="responsive-table__container"><table class="docutils align-default"> |
|
<colgroup> |
|
<col style="width: 18%"> |
|
<col style="width: 28%"> |
|
<col style="width: 53%"> |
|
</colgroup> |
|
<thead> |
|
<tr class="row-odd"><th class="head"><p>Attribute name</p></th> |
|
<th class="head"><p>Format</p></th> |
|
<th class="head"><p>Description</p></th> |
|
</tr> |
|
</thead> |
|
<tbody> |
|
<tr class="row-even"><td><p>args</p></td> |
|
<td><p>You shouldn’t need to |
|
format this yourself.</p></td> |
|
<td><p>The tuple of arguments merged into <code class="docutils literal notranslate"><span class="pre">msg</span></code> to |
|
produce <code class="docutils literal notranslate"><span class="pre">message</span></code>, or a dict whose values |
|
are used for the merge (when there is only one |
|
argument, and it is a dictionary).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>asctime</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(asctime)s</span></code></p></td> |
|
<td><p>Human-readable time when the |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> was created. By default |
|
this is of the form ‘2003-07-08 16:49:45,896’ |
|
(the numbers after the comma are millisecond |
|
portion of the time).</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>created</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(created)f</span></code></p></td> |
|
<td><p>Time when the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> was created |
|
(as returned by <a class="reference internal" href="https://docs.python.org/3/library/time.html#time.time" title="time.time"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.time()</span></code></a>).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>exc_info</p></td> |
|
<td><p>You shouldn’t need to |
|
format this yourself.</p></td> |
|
<td><p>Exception tuple (à la <code class="docutils literal notranslate"><span class="pre">sys.exc_info</span></code>) or, |
|
if no exception has occurred, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>filename</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(filename)s</span></code></p></td> |
|
<td><p>Filename portion of <code class="docutils literal notranslate"><span class="pre">pathname</span></code>.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>funcName</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(funcName)s</span></code></p></td> |
|
<td><p>Name of function containing the logging call.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>levelname</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(levelname)s</span></code></p></td> |
|
<td><p>Text logging level for the message |
|
(<code class="docutils literal notranslate"><span class="pre">'DEBUG'</span></code>, <code class="docutils literal notranslate"><span class="pre">'INFO'</span></code>, <code class="docutils literal notranslate"><span class="pre">'WARNING'</span></code>, |
|
<code class="docutils literal notranslate"><span class="pre">'ERROR'</span></code>, <code class="docutils literal notranslate"><span class="pre">'CRITICAL'</span></code>).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>levelno</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(levelno)s</span></code></p></td> |
|
<td><p>Numeric logging level for the message |
|
(<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="logging.DEBUG"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="logging.CRITICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code></a>).</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>lineno</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(lineno)d</span></code></p></td> |
|
<td><p>Source line number where the logging call was |
|
issued (if available).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>message</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(message)s</span></code></p></td> |
|
<td><p>The logged message, computed as <code class="docutils literal notranslate"><span class="pre">msg</span> <span class="pre">%</span> |
|
<span class="pre">args</span></code>. This is set when |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter.format" title="logging.Formatter.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Formatter.format()</span></code></a> is invoked.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>module</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(module)s</span></code></p></td> |
|
<td><p>Module (name portion of <code class="docutils literal notranslate"><span class="pre">filename</span></code>).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>msecs</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(msecs)d</span></code></p></td> |
|
<td><p>Millisecond portion of the time when the |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> was created.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>msg</p></td> |
|
<td><p>You shouldn’t need to |
|
format this yourself.</p></td> |
|
<td><p>The format string passed in the original |
|
logging call. Merged with <code class="docutils literal notranslate"><span class="pre">args</span></code> to |
|
produce <code class="docutils literal notranslate"><span class="pre">message</span></code>, or an arbitrary object |
|
(see <a class="reference internal" href="https://docs.python.org/3/howto/logging.html#arbitrary-object-messages"><span class="std std-ref">Using arbitrary objects as messages</span></a>).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>name</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(name)s</span></code></p></td> |
|
<td><p>Name of the logger used to log the call.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>pathname</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(pathname)s</span></code></p></td> |
|
<td><p>Full pathname of the source file where the |
|
logging call was issued (if available).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>process</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(process)d</span></code></p></td> |
|
<td><p>Process ID (if available).</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>processName</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(processName)s</span></code></p></td> |
|
<td><p>Process name (if available).</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>relativeCreated</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(relativeCreated)d</span></code></p></td> |
|
<td><p>Time in milliseconds when the LogRecord was |
|
created, relative to the time the logging |
|
module was loaded.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>stack_info</p></td> |
|
<td><p>You shouldn’t need to |
|
format this yourself.</p></td> |
|
<td><p>Stack frame information (where available) |
|
from the bottom of the stack in the current |
|
thread, up to and including the stack frame |
|
of the logging call which resulted in the |
|
creation of this record.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p>thread</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(thread)d</span></code></p></td> |
|
<td><p>Thread ID (if available).</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p>threadName</p></td> |
|
<td><p><code class="docutils literal notranslate"><span class="pre">%(threadName)s</span></code></p></td> |
|
<td><p>Thread name (if available).</p></td> |
|
</tr> |
|
</tbody> |
|
</table></div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.1: </span><em>processName</em> was added.</p> |
|
</div> |
|
</section> |
|
<section id="loggeradapter-objects"> |
|
<span id="logger-adapter"></span><h2>LoggerAdapter Objects<a class="headerlink" href="https://docs.python.org/3/library/logging.html#loggeradapter-objects" title="Permalink to this headline">¶</a></h2> |
|
<p><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> instances are used to conveniently pass contextual |
|
information into logging calls. For a usage example, see the section on |
|
<a class="reference internal" href="https://docs.python.org/3/howto/logging-cookbook.html#context-info"><span class="std std-ref">adding contextual information to your logging output</span></a>.</p> |
|
<dl class="py class"> |
|
<dt class="sig sig-object py" id="logging.LoggerAdapter"> |
|
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">LoggerAdapter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">logger</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extra</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns an instance of <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> initialized with an |
|
underlying <a class="reference internal" href="https://docs.python.org/3/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.</p> |
|
<dl class="py method"> |
|
<dt class="sig sig-object py" id="logging.LoggerAdapter.process"> |
|
<span class="sig-name descname"><span class="pre">process</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter.process" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Modifies the message and/or keyword arguments passed to a logging call in |
|
order to insert contextual information. This implementation takes the object |
|
passed as <em>extra</em> to the constructor and adds it to <em>kwargs</em> using key |
|
‘extra’. The return value is a (<em>msg</em>, <em>kwargs</em>) tuple which has the |
|
(possibly modified) versions of the arguments passed in.</p> |
|
</dd></dl> |
|
|
|
<dl class="py attribute"> |
|
<dt class="sig sig-object py" id="logging.LoggerAdapter.manager"> |
|
<span class="sig-name descname"><span class="pre">manager</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter.manager" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Delegates to the underlying <code class="xref py py-attr docutils literal notranslate"><span class="pre">manager`</span></code> on <em>logger</em>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py attribute"> |
|
<dt class="sig sig-object py" id="logging.LoggerAdapter._log"> |
|
<span class="sig-name descname"><span class="pre">_log</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter._log" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Delegates to the underlying <code class="xref py py-meth docutils literal notranslate"><span class="pre">_log`()</span></code> method on <em>logger</em>.</p> |
|
</dd></dl> |
|
|
|
<p>In addition to the above, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a> supports the following |
|
methods of <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a>: <a class="reference internal" href="https://docs.python.org/3/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="https://docs.python.org/3/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>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.warning" title="logging.Logger.warning"><code class="xref py py-meth docutils literal notranslate"><span class="pre">warning()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.error" title="logging.Logger.error"><code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.exception" title="logging.Logger.exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exception()</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.critical" title="logging.Logger.critical"><code class="xref py py-meth docutils literal notranslate"><span class="pre">critical()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.log" title="logging.Logger.log"><code class="xref py py-meth docutils literal notranslate"><span class="pre">log()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a> and |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hasHandlers()</span></code></a>. These methods have the same signatures as their |
|
counterparts in <a class="reference internal" href="https://docs.python.org/3/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 two types of instances |
|
interchangeably.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.isEnabledFor" title="logging.Logger.isEnabledFor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isEnabledFor()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.getEffectiveLevel" title="logging.Logger.getEffectiveLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getEffectiveLevel()</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.setLevel" title="logging.Logger.setLevel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setLevel()</span></code></a> and <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger.hasHandlers" title="logging.Logger.hasHandlers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hasHandlers()</span></code></a> methods were added |
|
to <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LoggerAdapter" title="logging.LoggerAdapter"><code class="xref py py-class docutils literal notranslate"><span class="pre">LoggerAdapter</span></code></a>. These methods delegate to the underlying logger.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>Attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">manager</span></code> and method <code class="xref py py-meth docutils literal notranslate"><span class="pre">_log()</span></code> were added, which |
|
delegate to the underlying logger and allow adapters to be nested.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
</section> |
|
<section id="thread-safety"> |
|
<h2>Thread Safety<a class="headerlink" href="https://docs.python.org/3/library/logging.html#thread-safety" title="Permalink to this headline">¶</a></h2> |
|
<p>The logging module is intended to be thread-safe without any special work |
|
needing to be done by its clients. It achieves this though using threading |
|
locks; there is one lock to serialize access to the module’s shared data, and |
|
each handler also creates a lock to serialize access to its underlying I/O.</p> |
|
<p>If you are implementing asynchronous signal handlers using the <a class="reference internal" href="https://docs.python.org/3/library/signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> |
|
module, you may not be able to use logging from within such handlers. This is |
|
because lock implementations in the <a class="reference internal" href="https://docs.python.org/3/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 are not always |
|
re-entrant, and so cannot be invoked from such signal handlers.</p> |
|
</section> |
|
<section id="module-level-functions"> |
|
<h2>Module-Level Functions<a class="headerlink" href="https://docs.python.org/3/library/logging.html#module-level-functions" title="Permalink to this headline">¶</a></h2> |
|
<p>In addition to the classes described above, there are a number of module-level |
|
functions.</p> |
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.getLogger"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">getLogger</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.getLogger" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return a logger with the specified name or, if name is <code class="docutils literal notranslate"><span class="pre">None</span></code>, return a |
|
logger which is the root logger of the hierarchy. If specified, the name is |
|
typically a dot-separated hierarchical name like <em>‘a’</em>, <em>‘a.b’</em> or <em>‘a.b.c.d’</em>. |
|
Choice of these names is entirely up to the developer who is using logging.</p> |
|
<p>All calls to this function with a given name return the same logger instance. |
|
This means that logger instances never need to be passed between different parts |
|
of an application.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.getLoggerClass"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">getLoggerClass</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.getLoggerClass" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return either the standard <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> class, or the last class passed to |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.setLoggerClass" title="logging.setLoggerClass"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLoggerClass()</span></code></a>. This function may be called from within a new class |
|
definition, to ensure that installing a customized <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal notranslate"><span class="pre">Logger</span></code></a> class will |
|
not undo customizations already applied by other code. For example:</p> |
|
<div class="highlight-python3 notranslate"><div class="highlight" style="position: relative;"><pre><span></span><span class="k">class</span> <span class="nc">MyLogger</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">getLoggerClass</span><span class="p">()):</span> |
|
<span class="c1"># ... override behaviour here</span> |
|
</pre></div> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.getLogRecordFactory"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">getLogRecordFactory</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.getLogRecordFactory" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Return a callable which is used to create a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>.</p> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.2: </span>This function has been provided, along with <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a>, |
|
to allow developers more control over how the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> |
|
representing a logging event is constructed.</p> |
|
</div> |
|
<p>See <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.setLogRecordFactory" title="logging.setLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">setLogRecordFactory()</span></code></a> for more information about the how the |
|
factory is called.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.debug"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.debug" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="logging.DEBUG"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code></a> on the root logger. The <em>msg</em> is the |
|
message format string, and the <em>args</em> are the arguments which are merged into |
|
<em>msg</em> using the string formatting operator. (Note that this means that you can |
|
use keywords in the format string, together with a single dictionary argument.)</p> |
|
<p>There are three keyword arguments in <em>kwargs</em> which are inspected: <em>exc_info</em> |
|
which, if it does not evaluate as false, causes exception information to be |
|
added to the logging message. If an exception tuple (in the format returned by |
|
<a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>) or an exception instance is provided, it is used; |
|
otherwise, <a class="reference internal" href="https://docs.python.org/3/library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a> is called to get the exception information.</p> |
|
<p>The second optional keyword argument is <em>stack_info</em>, which defaults to |
|
<code class="docutils literal notranslate"><span class="pre">False</span></code>. If true, stack information is added to the logging |
|
message, including the actual logging call. Note that this is not the same |
|
stack information as that displayed through specifying <em>exc_info</em>: The |
|
former is stack frames from the bottom of the stack up to the logging call |
|
in the current thread, whereas the latter is information about stack frames |
|
which have been unwound, following an exception, while searching for |
|
exception handlers.</p> |
|
<p>You can specify <em>stack_info</em> independently of <em>exc_info</em>, e.g. to just show |
|
how you got to a certain point in your code, even when no exceptions were |
|
raised. The stack frames are printed following a header line which says:</p> |
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Stack (most recent call last): |
|
</pre></div> |
|
</div> |
|
<p>This mimics the <code class="docutils literal notranslate"><span class="pre">Traceback</span> <span class="pre">(most</span> <span class="pre">recent</span> <span class="pre">call</span> <span class="pre">last):</span></code> which is used when |
|
displaying exception frames.</p> |
|
<p>The third optional keyword argument is <em>extra</em> which can be used to pass a |
|
dictionary which is used to populate the __dict__ of the LogRecord created for |
|
the logging event with user-defined attributes. These custom attributes can then |
|
be used as you like. For example, they could be incorporated into logged |
|
messages. For example:</p> |
|
<div class="highlight-python3 notranslate"><div class="highlight" style="position: relative;"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(clientip)-15s</span><span class="s1"> </span><span class="si">%(user)-8s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span> |
|
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="n">FORMAT</span><span class="p">)</span> |
|
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'clientip'</span><span class="p">:</span> <span class="s1">'192.168.0.1'</span><span class="p">,</span> <span class="s1">'user'</span><span class="p">:</span> <span class="s1">'fbloggs'</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="s1">'Protocol problem: </span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="s1">'connection reset'</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="n">d</span><span class="p">)</span> |
|
</pre></div> |
|
</div> |
|
<p>would print something like:</p> |
|
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset |
|
</pre></div> |
|
</div> |
|
<p>The keys in the dictionary passed in <em>extra</em> should not clash with the keys used |
|
by the logging system. (See the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> documentation for more |
|
information on which keys are used by the logging system.)</p> |
|
<p>If you choose to use these attributes in logged messages, you need to exercise |
|
some care. In the above example, for instance, the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> has been |
|
set up with a format string which expects ‘clientip’ and ‘user’ in the attribute |
|
dictionary of the LogRecord. If these are missing, the message will not be |
|
logged because a string formatting exception will occur. So in this case, you |
|
always need to pass the <em>extra</em> dictionary with these keys.</p> |
|
<p>While this might be annoying, this feature is intended for use in specialized |
|
circumstances, such as multi-threaded servers where the same code executes in |
|
many contexts, and interesting conditions which arise are dependent on this |
|
context (such as remote client IP address and authenticated user name, in the |
|
above example). In such circumstances, it is likely that specialized |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a>s would be used with particular <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a>s.</p> |
|
<p>This function (as well as <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.info" title="logging.info"><code class="xref py py-func docutils literal notranslate"><span class="pre">info()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.warning" title="logging.warning"><code class="xref py py-func docutils literal notranslate"><span class="pre">warning()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.error" title="logging.error"><code class="xref py py-func docutils literal notranslate"><span class="pre">error()</span></code></a> and |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.critical" title="logging.critical"><code class="xref py py-func docutils literal notranslate"><span class="pre">critical()</span></code></a>) will call <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> if the root logger doesn’t |
|
have any handler attached.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>stack_info</em> parameter was added.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.info"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.info" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a> on the root logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.warning"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">warning</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.warning" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a> on the root logger. The arguments |
|
are interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>There is an obsolete function <code class="docutils literal notranslate"><span class="pre">warn</span></code> which is functionally |
|
identical to <code class="docutils literal notranslate"><span class="pre">warning</span></code>. As <code class="docutils literal notranslate"><span class="pre">warn</span></code> is deprecated, please do not use |
|
it - use <code class="docutils literal notranslate"><span class="pre">warning</span></code> instead.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.error"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">error</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.error" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a> on the root logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.critical"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">critical</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.critical" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="logging.CRITICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code></a> on the root logger. The arguments |
|
are interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.exception"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.exception" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a> on the root logger. The arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>. Exception info is added to the logging |
|
message. This function should only be called from an exception handler.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.log"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">log</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.log" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Logs a message with level <em>level</em> on the root logger. The other arguments are |
|
interpreted as for <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.disable"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">disable</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">CRITICAL</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.disable" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Provides an overriding level <em>level</em> for all loggers which takes precedence over |
|
the logger’s own level. When the need arises to temporarily throttle logging |
|
output down across the whole application, this function can be useful. Its |
|
effect is to disable all logging calls of severity <em>level</em> and below, so that |
|
if you call it with a value of INFO, then all INFO and DEBUG events would be |
|
discarded, whereas those of severity WARNING and above would be processed |
|
according to the logger’s effective level. If |
|
<code class="docutils literal notranslate"><span class="pre">logging.disable(logging.NOTSET)</span></code> is called, it effectively removes this |
|
overriding level, so that logging output again depends on the effective |
|
levels of individual loggers.</p> |
|
<p>Note that if you have defined any custom logging level higher than |
|
<code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code> (this is not recommended), you won’t be able to rely on the |
|
default value for the <em>level</em> parameter, but will have to explicitly supply a |
|
suitable value.</p> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>level</em> parameter was defaulted to level <code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code>. See |
|
<a class="reference external" href="https://bugs.python.org/issue?@action=redirect&bpo=28524">bpo-28524</a> for more information about this change.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.addLevelName"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">addLevelName</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">levelName</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.addLevelName" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Associates level <em>level</em> with text <em>levelName</em> in an internal dictionary, which is |
|
used to map numeric levels to a textual representation, for example when a |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> formats a message. This function can also be used to define |
|
your own levels. The only constraints are that all levels used must be |
|
registered using this function, levels should be positive integers and they |
|
should increase in increasing order of severity.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>If you are thinking of defining your own levels, please see the |
|
section on <a class="reference internal" href="https://docs.python.org/3/howto/logging.html#custom-levels"><span class="std std-ref">Custom Levels</span></a>.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.getLevelNamesMapping"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">getLevelNamesMapping</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.getLevelNamesMapping" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns a mapping from level names to their corresponding logging levels. For example, the |
|
string “CRITICAL” maps to <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="logging.CRITICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code></a>. The returned mapping is copied from an internal |
|
mapping on each call to this function.</p> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.11.</span></p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.getLevelName"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">getLevelName</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.getLevelName" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Returns the textual or numeric representation of logging level <em>level</em>.</p> |
|
<p>If <em>level</em> is one of the predefined levels <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.CRITICAL" title="logging.CRITICAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.ERROR" title="logging.ERROR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.INFO" title="logging.INFO"><code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code></a> or <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.DEBUG" title="logging.DEBUG"><code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code></a> then you get the |
|
corresponding string. If you have associated levels with names using |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.addLevelName" title="logging.addLevelName"><code class="xref py py-func docutils literal notranslate"><span class="pre">addLevelName()</span></code></a> then the name you have associated with <em>level</em> is |
|
returned. If a numeric value corresponding to one of the defined levels is |
|
passed in, the corresponding string representation is returned.</p> |
|
<p>The <em>level</em> parameter also accepts a string representation of the level such |
|
as ‘INFO’. In such cases, this functions returns the corresponding numeric |
|
value of the level.</p> |
|
<p>If no matching numeric or string value is passed in, the string |
|
‘Level %s’ % level is returned.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>Levels are internally integers (as they need to be compared in the |
|
logging logic). This function is used to convert between an integer level |
|
and the level name displayed in the formatted log output by means of the |
|
<code class="docutils literal notranslate"><span class="pre">%(levelname)s</span></code> format specifier (see <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-attributes"><span class="std std-ref">LogRecord attributes</span></a>), and |
|
vice versa.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>In Python versions earlier than 3.4, this function could also be passed a |
|
text level, and would return the corresponding numeric value of the level. |
|
This undocumented behaviour was considered a mistake, and was removed in |
|
Python 3.4, but reinstated in 3.4.2 due to retain backward compatibility.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.makeLogRecord"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">makeLogRecord</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">attrdict</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.makeLogRecord" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Creates and returns a new <a class="reference internal" href="https://docs.python.org/3/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 whose attributes are |
|
defined by <em>attrdict</em>. This function is useful for taking a pickled |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> attribute dictionary, sent over a socket, and reconstituting |
|
it as a <a class="reference internal" href="https://docs.python.org/3/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 at the receiving end.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.basicConfig"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">basicConfig</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.basicConfig" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Does basic configuration for the logging system by creating a |
|
<a class="reference internal" href="https://docs.python.org/3/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> with a default <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> and adding it to the |
|
root logger. The functions <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.debug" title="logging.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.info" title="logging.info"><code class="xref py py-func docutils literal notranslate"><span class="pre">info()</span></code></a>, <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.warning" title="logging.warning"><code class="xref py py-func docutils literal notranslate"><span class="pre">warning()</span></code></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.error" title="logging.error"><code class="xref py py-func docutils literal notranslate"><span class="pre">error()</span></code></a> and <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.critical" title="logging.critical"><code class="xref py py-func docutils literal notranslate"><span class="pre">critical()</span></code></a> will call <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> automatically |
|
if no handlers are defined for the root logger.</p> |
|
<p>This function does nothing if the root logger already has handlers |
|
configured, unless the keyword argument <em>force</em> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p> |
|
<div class="admonition note"> |
|
<p class="admonition-title">Note</p> |
|
<p>This function should be called from the main thread |
|
before other threads are started. In versions of Python prior to |
|
2.7.1 and 3.2, if this function is called from multiple threads, |
|
it is possible (in rare circumstances) that a handler will be added |
|
to the root logger more than once, leading to unexpected results |
|
such as messages being duplicated in the log.</p> |
|
</div> |
|
<p>The following keyword arguments are supported.</p> |
|
<div class="responsive-table__container"><table class="docutils align-default"> |
|
<colgroup> |
|
<col style="width: 24%"> |
|
<col style="width: 76%"> |
|
</colgroup> |
|
<thead> |
|
<tr class="row-odd"><th class="head"><p>Format</p></th> |
|
<th class="head"><p>Description</p></th> |
|
</tr> |
|
</thead> |
|
<tbody> |
|
<tr class="row-even"><td><p><em>filename</em></p></td> |
|
<td><p>Specifies that a <a class="reference internal" href="https://docs.python.org/3/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> be |
|
created, using the specified filename, |
|
rather than a <a class="reference internal" href="https://docs.python.org/3/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>.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p><em>filemode</em></p></td> |
|
<td><p>If <em>filename</em> is specified, open the file |
|
in this <a class="reference internal" href="https://docs.python.org/3/library/functions.html#filemodes"><span class="std std-ref">mode</span></a>. Defaults |
|
to <code class="docutils literal notranslate"><span class="pre">'a'</span></code>.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p><em>format</em></p></td> |
|
<td><p>Use the specified format string for the |
|
handler. Defaults to attributes |
|
<code class="docutils literal notranslate"><span class="pre">levelname</span></code>, <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">message</span></code> |
|
separated by colons.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p><em>datefmt</em></p></td> |
|
<td><p>Use the specified date/time format, as |
|
accepted by <a class="reference internal" href="https://docs.python.org/3/library/time.html#time.strftime" title="time.strftime"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.strftime()</span></code></a>.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p><em>style</em></p></td> |
|
<td><p>If <em>format</em> is specified, use this style |
|
for the format string. One of <code class="docutils literal notranslate"><span class="pre">'%'</span></code>, |
|
<code class="docutils literal notranslate"><span class="pre">'{'</span></code> or <code class="docutils literal notranslate"><span class="pre">'$'</span></code> for <a class="reference internal" href="https://docs.python.org/3/library/stdtypes.html#old-string-formatting"><span class="std std-ref">printf-style</span></a>, |
|
<a class="reference internal" href="https://docs.python.org/3/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="https://docs.python.org/3/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> respectively. |
|
Defaults to <code class="docutils literal notranslate"><span class="pre">'%'</span></code>.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p><em>level</em></p></td> |
|
<td><p>Set the root logger level to the specified |
|
<a class="reference internal" href="https://docs.python.org/3/library/logging.html#levels"><span class="std std-ref">level</span></a>.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p><em>stream</em></p></td> |
|
<td><p>Use the specified stream to initialize the |
|
<a class="reference internal" href="https://docs.python.org/3/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>. Note that this |
|
argument is incompatible with <em>filename</em> - |
|
if both are present, a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is |
|
raised.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p><em>handlers</em></p></td> |
|
<td><p>If specified, this should be an iterable of |
|
already created handlers to add to the root |
|
logger. Any handlers which don’t already |
|
have a formatter set will be assigned the |
|
default formatter created in this function. |
|
Note that this argument is incompatible |
|
with <em>filename</em> or <em>stream</em> - if both |
|
are present, a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p><em>force</em></p></td> |
|
<td><p>If this keyword argument is specified as |
|
true, any existing handlers attached to the |
|
root logger are removed and closed, before |
|
carrying out the configuration as specified |
|
by the other arguments.</p></td> |
|
</tr> |
|
<tr class="row-odd"><td><p><em>encoding</em></p></td> |
|
<td><p>If this keyword argument is specified along |
|
with <em>filename</em>, its value is used when the |
|
<a class="reference internal" href="https://docs.python.org/3/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> is created, and thus |
|
used when opening the output file.</p></td> |
|
</tr> |
|
<tr class="row-even"><td><p><em>errors</em></p></td> |
|
<td><p>If this keyword argument is specified along |
|
with <em>filename</em>, its value is used when the |
|
<a class="reference internal" href="https://docs.python.org/3/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> is created, and thus |
|
used when opening the output file. If not |
|
specified, the value ‘backslashreplace’ is |
|
used. Note that if <code class="docutils literal notranslate"><span class="pre">None</span></code> is specified, |
|
it will be passed as such to <a class="reference internal" href="https://docs.python.org/3/library/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>, |
|
which means that it will be treated the |
|
same as passing ‘errors’.</p></td> |
|
</tr> |
|
</tbody> |
|
</table></div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>style</em> argument was added.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>The <em>handlers</em> argument was added. Additional checks were added to |
|
catch situations where incompatible arguments are specified (e.g. |
|
<em>handlers</em> together with <em>stream</em> or <em>filename</em>, or <em>stream</em> |
|
together with <em>filename</em>).</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>force</em> argument was added.</p> |
|
</div> |
|
<div class="versionchanged"> |
|
<p><span class="versionmodified changed">Changed in version 3.9: </span>The <em>encoding</em> and <em>errors</em> arguments were added.</p> |
|
</div> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.shutdown"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">shutdown</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.shutdown" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Informs the logging system to perform an orderly shutdown by flushing and |
|
closing all handlers. This should be called at application exit and no |
|
further use of the logging system should be made after this call.</p> |
|
<p>When the logging module is imported, it registers this function as an exit |
|
handler (see <a class="reference internal" href="https://docs.python.org/3/library/atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">atexit</span></code></a>), so normally there’s no need to do that |
|
manually.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.setLoggerClass"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">setLoggerClass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">klass</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.setLoggerClass" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Tells the logging system to use the class <em>klass</em> when instantiating a logger. |
|
The class should define <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> such that only a name argument is |
|
required, and the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> should call <code class="xref py py-meth docutils literal notranslate"><span class="pre">Logger.__init__()</span></code>. This |
|
function is typically called before any loggers are instantiated by applications |
|
which need to use custom logger behavior. After this call, as at any other |
|
time, do not instantiate loggers directly using the subclass: continue to use |
|
the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.getLogger" title="logging.getLogger"><code class="xref py py-func docutils literal notranslate"><span class="pre">logging.getLogger()</span></code></a> API to get your loggers.</p> |
|
</dd></dl> |
|
|
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.setLogRecordFactory"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">setLogRecordFactory</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">factory</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.setLogRecordFactory" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>Set a callable which is used to create a <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a>.</p> |
|
<dl class="field-list simple"> |
|
<dt class="field-odd">Parameters</dt> |
|
<dd class="field-odd"><p><strong>factory</strong> – The factory callable to be used to instantiate a log record.</p> |
|
</dd> |
|
</dl> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.2: </span>This function has been provided, along with <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.getLogRecordFactory" title="logging.getLogRecordFactory"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLogRecordFactory()</span></code></a>, to |
|
allow developers more control over how the <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal notranslate"><span class="pre">LogRecord</span></code></a> representing |
|
a logging event is constructed.</p> |
|
</div> |
|
<p>The factory has the following signature:</p> |
|
<p><code class="docutils literal notranslate"><span class="pre">factory(name,</span> <span class="pre">level,</span> <span class="pre">fn,</span> <span class="pre">lno,</span> <span class="pre">msg,</span> <span class="pre">args,</span> <span class="pre">exc_info,</span> <span class="pre">func=None,</span> <span class="pre">sinfo=None,</span> <span class="pre">**kwargs)</span></code></p> |
|
<blockquote> |
|
<div><dl class="field-list simple"> |
|
<dt class="field-odd">name</dt> |
|
<dd class="field-odd"><p>The logger name.</p> |
|
</dd> |
|
<dt class="field-even">level</dt> |
|
<dd class="field-even"><p>The logging level (numeric).</p> |
|
</dd> |
|
<dt class="field-odd">fn</dt> |
|
<dd class="field-odd"><p>The full pathname of the file where the logging call was made.</p> |
|
</dd> |
|
<dt class="field-even">lno</dt> |
|
<dd class="field-even"><p>The line number in the file where the logging call was made.</p> |
|
</dd> |
|
<dt class="field-odd">msg</dt> |
|
<dd class="field-odd"><p>The logging message.</p> |
|
</dd> |
|
<dt class="field-even">args</dt> |
|
<dd class="field-even"><p>The arguments for the logging message.</p> |
|
</dd> |
|
<dt class="field-odd">exc_info</dt> |
|
<dd class="field-odd"><p>An exception tuple, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> |
|
</dd> |
|
<dt class="field-even">func</dt> |
|
<dd class="field-even"><p>The name of the function or method which invoked the logging |
|
call.</p> |
|
</dd> |
|
<dt class="field-odd">sinfo</dt> |
|
<dd class="field-odd"><p>A stack traceback such as is provided by |
|
<a class="reference internal" href="https://docs.python.org/3/library/traceback.html#traceback.print_stack" title="traceback.print_stack"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.print_stack()</span></code></a>, showing the call hierarchy.</p> |
|
</dd> |
|
<dt class="field-even">kwargs</dt> |
|
<dd class="field-even"><p>Additional keyword arguments.</p> |
|
</dd> |
|
</dl> |
|
</div></blockquote> |
|
</dd></dl> |
|
|
|
</section> |
|
<section id="module-level-attributes"> |
|
<h2>Module-Level Attributes<a class="headerlink" href="https://docs.python.org/3/library/logging.html#module-level-attributes" title="Permalink to this headline">¶</a></h2> |
|
<dl class="py attribute"> |
|
<dt class="sig sig-object py" id="logging.lastResort"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">lastResort</span></span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.lastResort" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>A “handler of last resort” is available through this attribute. This |
|
is a <a class="reference internal" href="https://docs.python.org/3/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> writing to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> with a level of |
|
<code class="docutils literal notranslate"><span class="pre">WARNING</span></code>, and is used to handle logging events in the absence of any |
|
logging configuration. The end result is to just print the message to |
|
<code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>. This replaces the earlier error message saying that |
|
“no handlers could be found for logger XYZ”. If you need the earlier |
|
behaviour for some reason, <code class="docutils literal notranslate"><span class="pre">lastResort</span></code> can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> |
|
<div class="versionadded"> |
|
<p><span class="versionmodified added">New in version 3.2.</span></p> |
|
</div> |
|
</dd></dl> |
|
|
|
</section> |
|
<section id="integration-with-the-warnings-module"> |
|
<h2>Integration with the warnings module<a class="headerlink" href="https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module" title="Permalink to this headline">¶</a></h2> |
|
<p>The <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.captureWarnings" title="logging.captureWarnings"><code class="xref py py-func docutils literal notranslate"><span class="pre">captureWarnings()</span></code></a> function can be used to integrate <a class="reference internal" href="https://docs.python.org/3/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> |
|
with the <a class="reference internal" href="https://docs.python.org/3/library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module.</p> |
|
<dl class="py function"> |
|
<dt class="sig sig-object py" id="logging.captureWarnings"> |
|
<span class="sig-prename descclassname"><span class="pre">logging.</span></span><span class="sig-name descname"><span class="pre">captureWarnings</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">capture</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="https://docs.python.org/3/library/logging.html#logging.captureWarnings" title="Permalink to this definition">¶</a></dt> |
|
<dd><p>This function is used to turn the capture of warnings by logging on and |
|
off.</p> |
|
<p>If <em>capture</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, warnings issued by the <a class="reference internal" href="https://docs.python.org/3/library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module will |
|
be redirected to the logging system. Specifically, a warning will be |
|
formatted using <a class="reference internal" href="https://docs.python.org/3/library/warnings.html#warnings.formatwarning" title="warnings.formatwarning"><code class="xref py py-func docutils literal notranslate"><span class="pre">warnings.formatwarning()</span></code></a> and the resulting string |
|
logged to a logger named <code class="docutils literal notranslate"><span class="pre">'py.warnings'</span></code> with a severity of <a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging.WARNING" title="logging.WARNING"><code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code></a>.</p> |
|
<p>If <em>capture</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, the redirection of warnings to the logging system |
|
will stop, and warnings will be redirected to their original destinations |
|
(i.e. those in effect before <code class="docutils literal notranslate"><span class="pre">captureWarnings(True)</span></code> was called).</p> |
|
</dd></dl> |
|
|
|
<div class="admonition seealso"> |
|
<p class="admonition-title">See also</p> |
|
<dl class="simple"> |
|
<dt>Module <a class="reference internal" href="https://docs.python.org/3/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> |
|
</dd> |
|
<dt>Module <a class="reference internal" href="https://docs.python.org/3/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> |
|
</dd> |
|
<dt><span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0282/"><strong>PEP 282</strong></a> - A Logging System</dt><dd><p>The proposal which described this feature for inclusion in the Python standard |
|
library.</p> |
|
</dd> |
|
<dt><a class="reference external" href="https://old.red-dove.com/python_logging.html">Original Python logging package</a></dt><dd><p>This is the original source for the <a class="reference internal" href="https://docs.python.org/3/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> package. The version of the |
|
package available from this site is suitable for use with Python 1.5.2, 2.1.x |
|
and 2.2.x, which do not include the <a class="reference internal" href="https://docs.python.org/3/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> package in the standard |
|
library.</p> |
|
</dd> |
|
</dl> |
|
</div> |
|
</section> |
|
</section> |
|
|
|
|
|
<div class="clearer"></div> |
|
</div> |
|
</div> |
|
</div> |
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
|
<div class="sphinxsidebarwrapper"> |
|
<div> |
|
<h3><a href="https://docs.python.org/3/contents.html">Table of Contents</a></h3> |
|
<ul> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> — Logging facility for Python</a><ul> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logger-objects">Logger Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logging-levels">Logging Levels</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#handler-objects">Handler Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#formatter-objects">Formatter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#filter-objects">Filter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-objects">LogRecord Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#logrecord-attributes">LogRecord attributes</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#loggeradapter-objects">LoggerAdapter Objects</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#thread-safety">Thread Safety</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#module-level-functions">Module-Level Functions</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#module-level-attributes">Module-Level Attributes</a></li> |
|
<li><a class="reference internal" href="https://docs.python.org/3/library/logging.html#integration-with-the-warnings-module">Integration with the warnings module</a></li> |
|
</ul> |
|
</li> |
|
</ul> |
|
|
|
</div> |
|
<div> |
|
<h4>Previous topic</h4> |
|
<p class="topless"><a href="https://docs.python.org/3/library/getopt.html" title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code> — C-style parser for command line options</a></p> |
|
</div> |
|
<div> |
|
<h4>Next topic</h4> |
|
<p class="topless"><a href="https://docs.python.org/3/library/logging.config.html" title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code> — Logging configuration</a></p> |
|
</div> |
|
<div role="note" aria-label="source link"> |
|
<h3>This Page</h3> |
|
<ul class="this-page-menu"> |
|
<li><a href="https://docs.python.org/3/bugs.html">Report a Bug</a></li> |
|
<li> |
|
<a href="https://github.com/python/cpython/blob/3.11/Doc/library/logging.rst" rel="nofollow">Show Source |
|
</a> |
|
</li> |
|
</ul> |
|
</div> |
|
</div> |
|
<div id="sidebarbutton"><span>«</span></div></div> |
|
<div class="clearer"></div> |
|
</div> |
|
<div class="related" role="navigation" aria-label="related navigation"> |
|
<h3>Navigation</h3> |
|
<ul> |
|
<li class="right" style="margin-right: 10px"> |
|
<a href="https://docs.python.org/3/genindex.html" title="General Index">index</a></li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/py-modindex.html" title="Python Module Index">modules</a> |</li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/library/logging.config.html" title="logging.config — Logging configuration">next</a> |</li> |
|
<li class="right"> |
|
<a href="https://docs.python.org/3/library/getopt.html" title="getopt — C-style parser for command line options">previous</a> |</li> |
|
|
|
<li><img src="./test_files/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"></li> |
|
<li><a href="https://www.python.org/">Python</a> »</li> |
|
<li class="switchers"> |
|
<div class="language_switcher_placeholder"><select id="language_select"><option value="en" selected="selected">English</option><option value="es">Spanish</option><option value="fr">French</option><option value="ja">Japanese</option><option value="ko">Korean</option><option value="pt-br">Brazilian Portuguese</option><option value="tr">Turkish</option><option value="zh-cn">Simplified Chinese</option><option value="zh-tw">Traditional Chinese</option></select></div> |
|
<div class="version_switcher_placeholder"><select id="version_select"><option value="3.13">dev (3.13)</option><option value="3.12">pre (3.12)</option><option value="3.11" selected="selected">3.11.5</option><option value="3.10">3.10</option><option value="3.9">3.9</option><option value="3.8">3.8</option><option value="3.7">3.7</option><option value="3.6">3.6</option><option value="3.5">3.5</option><option value="2.7">2.7</option></select></div> |
|
</li> |
|
<li> |
|
|
|
</li> |
|
<li id="cpython-language-and-version"> |
|
<a href="https://docs.python.org/3/index.html">3.11.5 Documentation</a> » |
|
</li> |
|
|
|
<li class="nav-item nav-item-1"><a href="https://docs.python.org/3/library/index.html">The Python Standard Library</a> »</li> |
|
<li class="nav-item nav-item-2"><a href="https://docs.python.org/3/library/allos.html">Generic Operating System Services</a> »</li> |
|
<li class="nav-item nav-item-this"><a href="https://docs.python.org/3/library/logging.html"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> — Logging facility for Python</a></li> |
|
<li class="right"> |
|
|
|
|
|
<div class="inline-search" role="search"> |
|
<form class="inline-search" action="https://docs.python.org/3/search.html" method="get"> |
|
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q"> |
|
<input type="submit" value="Go"> |
|
</form> |
|
</div> |
|
| |
|
</li> |
|
<li class="right"> |
|
<label class="theme-selector-label"> |
|
Theme |
|
<select class="theme-selector" oninput="activateTheme(this.value)"> |
|
<option value="auto" selected="">Auto</option> |
|
<option value="light">Light</option> |
|
<option value="dark">Dark</option> |
|
</select> |
|
</label> |</li> |
|
|
|
</ul> |
|
</div> |
|
<div class="footer"> |
|
© <a href="https://docs.python.org/3/copyright.html">Copyright</a> 2001-2023, Python Software Foundation. |
|
<br> |
|
This page is licensed under the Python Software Foundation License Version 2. |
|
<br> |
|
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. |
|
<br> |
|
See <a href="https://docs.python.org/license.html">History and License</a> for more information.<br> |
|
<br> |
|
|
|
The Python Software Foundation is a non-profit corporation. |
|
<a href="https://www.python.org/psf/donations/">Please donate.</a> |
|
<br> |
|
<br> |
|
|
|
Last updated on Sep 14, 2023. |
|
<a href="https://docs.python.org/bugs.html">Found a bug</a>? |
|
<br> |
|
|
|
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.5.0. |
|
</div> |
|
|
|
<script type="text/javascript" src="./test_files/switchers.js.download"></script> |
|
|
|
<div id="hl-aria-live-message-container" aria-live="polite" class="visually-hidden"></div><div id="hl-aria-live-alert-container" role="alert" aria-live="assertive" class="visually-hidden"></div></body><grammarly-desktop-integration data-grammarly-shadow-root="true"><template shadowrootmode="open"><style> |
|
div.grammarly-desktop-integration { |
|
position: absolute; |
|
width: 1px; |
|
height: 1px; |
|
padding: 0; |
|
margin: -1px; |
|
overflow: hidden; |
|
clip: rect(0, 0, 0, 0); |
|
white-space: nowrap; |
|
border: 0; |
|
-moz-user-select: none; |
|
-webkit-user-select: none; |
|
-ms-user-select:none; |
|
user-select:none; |
|
} |
|
|
|
div.grammarly-desktop-integration:before { |
|
content: attr(data-content); |
|
} |
|
</style><div aria-label="grammarly-integration" role="group" tabindex="-1" class="grammarly-desktop-integration" data-content="{"mode":"limited","isActive":false,"isUserDisabled":false}"></div></template></grammarly-desktop-integration></html>
|
|
|