1603 lines
132 KiB
HTML
1603 lines
132 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>logging — Logging facility for Python — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="logging.config — Logging configuration" href="logging.config.html" />
|
||
<link rel="prev" title="getopt — C-style parser for command line options" href="getopt.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/logging.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.config.html" title="logging.config — Logging configuration"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="getopt.html" title="getopt — C-style parser for command line options"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-logging">
|
||
<span id="logging-logging-facility-for-python"></span><h1><a class="reference internal" href="#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="#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.7/Lib/logging/__init__.py">Lib/logging/__init__.py</a></p>
|
||
<div 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="../howto/logging.html#logging-basic-tutorial"><span class="std std-ref">Basic Tutorial</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging.html#logging-advanced-tutorial"><span class="std std-ref">Advanced Tutorial</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging-cookbook.html#logging-cookbook"><span class="std std-ref">Logging Cookbook</span></a></p></li>
|
||
</ul>
|
||
</div>
|
||
<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 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 see the
|
||
tutorials (see the links on the right).</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>
|
||
<div class="section" id="logger-objects">
|
||
<span id="logger"></span><h2>Logger Objects<a class="headerlink" href="#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="#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="class">
|
||
<dt id="logging.Logger">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Logger</code><a class="headerlink" href="#logging.Logger" title="Permalink to this definition">¶</a></dt>
|
||
<dd><dl class="attribute">
|
||
<dt id="logging.Logger.propagate">
|
||
<code class="descname">propagate</code><a class="headerlink" href="#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>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="method">
|
||
<dt id="logging.Logger.setLevel">
|
||
<code class="descname">setLevel</code><span class="sig-paren">(</span><em>level</em><span class="sig-paren">)</span><a class="headerlink" href="#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 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> (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 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>.</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="#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 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code>. Note, however, that levels are internally stored
|
||
as integers, and methods such as e.g. <a class="reference internal" href="#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="#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="method">
|
||
<dt id="logging.Logger.isEnabledFor">
|
||
<code class="descname">isEnabledFor</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.isEnabledFor" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Indicates if a message of severity <em>lvl</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(lvl)</span></code> and then the logger’s effective level as determined
|
||
by <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.getEffectiveLevel">
|
||
<code class="descname">getEffectiveLevel</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.getEffectiveLevel" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Indicates the effective level for this logger. If a value other than
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> has been set using <a class="reference internal" href="#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
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> is found, and that value is returned. The value returned is
|
||
an integer, typically one of <code class="xref py py-const docutils literal notranslate"><span class="pre">logging.DEBUG</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">logging.INFO</span></code>
|
||
etc.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.getChild">
|
||
<code class="descname">getChild</code><span class="sig-paren">(</span><em>suffix</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Logger.debug">
|
||
<code class="descname">debug</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.debug" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> 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.)</p>
|
||
<p>There are three keyword arguments in <em>kwargs</em> which are inspected:
|
||
<em>exc_info</em>, <em>stack_info</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="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="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 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"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)-15s</span><span class="s1"> </span><span class="si">%(clientip)s</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 <a class="reference internal" href="#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="#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="#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="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a>s.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New 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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.info">
|
||
<code class="descname">info</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.info" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> on this logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.warning">
|
||
<code class="descname">warning</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.warning" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> on this logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.error">
|
||
<code class="descname">error</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> on this logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.critical">
|
||
<code class="descname">critical</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.critical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code> on this logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.log">
|
||
<code class="descname">log</code><span class="sig-paren">(</span><em>lvl</em>, <em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.log" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with integer level <em>lvl</em> on this logger. The other arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.exception">
|
||
<code class="descname">exception</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.exception" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> on this logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Logger.addFilter">
|
||
<code class="descname">addFilter</code><span class="sig-paren">(</span><em>filter</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Logger.removeFilter">
|
||
<code class="descname">removeFilter</code><span class="sig-paren">(</span><em>filter</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Logger.filter">
|
||
<code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Logger.filter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Applies this logger’s filters to the record and returns a true value 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="method">
|
||
<dt id="logging.Logger.addHandler">
|
||
<code class="descname">addHandler</code><span class="sig-paren">(</span><em>hdlr</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Logger.removeHandler">
|
||
<code class="descname">removeHandler</code><span class="sig-paren">(</span><em>hdlr</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Logger.findCaller">
|
||
<code class="descname">findCaller</code><span class="sig-paren">(</span><em>stack_info=False</em><span class="sig-paren">)</span><a class="headerlink" href="#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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Logger.handle">
|
||
<code class="descname">handle</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="method">
|
||
<dt id="logging.Logger.makeRecord">
|
||
<code class="descname">makeRecord</code><span class="sig-paren">(</span><em>name</em>, <em>lvl</em>, <em>fn</em>, <em>lno</em>, <em>msg</em>, <em>args</em>, <em>exc_info</em>, <em>func=None</em>, <em>extra=None</em>, <em>sinfo=None</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="method">
|
||
<dt id="logging.Logger.hasHandlers">
|
||
<code class="descname">hasHandlers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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>
|
||
|
||
</div>
|
||
<div class="section" id="logging-levels">
|
||
<span id="levels"></span><h2>Logging Levels<a class="headerlink" href="#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>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 48%" />
|
||
<col style="width: 52%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Level</p></th>
|
||
<th class="head"><p>Numeric value</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code></p></td>
|
||
<td><p>50</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ERROR</span></code></p></td>
|
||
<td><p>40</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">WARNING</span></code></p></td>
|
||
<td><p>30</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INFO</span></code></p></td>
|
||
<td><p>20</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DEBUG</span></code></p></td>
|
||
<td><p>10</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">NOTSET</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<div class="section" id="handler-objects">
|
||
<span id="handler"></span><h2>Handler Objects<a class="headerlink" href="#handler-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>Handlers have the following attributes and methods. Note that <a class="reference internal" href="#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 <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method in subclasses needs to call
|
||
<a class="reference internal" href="#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="class">
|
||
<dt id="logging.Handler">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Handler</code><a class="headerlink" href="#logging.Handler" title="Permalink to this definition">¶</a></dt>
|
||
<dd><dl class="method">
|
||
<dt id="logging.Handler.__init__">
|
||
<code class="descname">__init__</code><span class="sig-paren">(</span><em>level=NOTSET</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.__init__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Initializes the <a class="reference internal" href="#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="#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="method">
|
||
<dt id="logging.Handler.createLock">
|
||
<code class="descname">createLock</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.acquire">
|
||
<code class="descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.acquire" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Acquires the thread lock created with <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Handler.release">
|
||
<code class="descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.release" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Releases the thread lock acquired with <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Handler.setLevel">
|
||
<code class="descname">setLevel</code><span class="sig-paren">(</span><em>level</em><span class="sig-paren">)</span><a class="headerlink" href="#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 <code class="xref py py-const docutils literal notranslate"><span class="pre">NOTSET</span></code> (which causes all messages to be
|
||
processed).</p>
|
||
<p>See <a class="reference internal" href="#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 <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Handler.setFormatter">
|
||
<code class="descname">setFormatter</code><span class="sig-paren">(</span><em>fmt</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.setFormatter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Sets the <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Handler.addFilter">
|
||
<code class="descname">addFilter</code><span class="sig-paren">(</span><em>filter</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.removeFilter">
|
||
<code class="descname">removeFilter</code><span class="sig-paren">(</span><em>filter</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.filter">
|
||
<code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Handler.filter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Applies this handler’s filters to the record and returns a true value 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="method">
|
||
<dt id="logging.Handler.flush">
|
||
<code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="#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="method">
|
||
<dt id="logging.Handler.handle">
|
||
<code class="descname">handle</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.handleError">
|
||
<code class="descname">handleError</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="method">
|
||
<dt id="logging.Handler.format">
|
||
<code class="descname">format</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="method">
|
||
<dt id="logging.Handler.emit">
|
||
<code class="descname">emit</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>For a list of handlers included as standard, see <a class="reference internal" href="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>
|
||
</div>
|
||
<div class="section" id="formatter-objects">
|
||
<span id="id1"></span><h2>Formatter Objects<a class="headerlink" href="#formatter-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="reference internal" href="#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="#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="#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="#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="#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="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="#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="#logrecord-attributes"><span class="std std-ref">LogRecord attributes</span></a>.</p>
|
||
<dl class="class">
|
||
<dt id="logging.Formatter">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Formatter</code><span class="sig-paren">(</span><em>fmt=None</em>, <em>datefmt=None</em>, <em>style='%'</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a new instance of the <a class="reference internal" href="#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="#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="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="string.html#string.Template" title="string.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">string.Template</span></code></a>. See <a class="reference internal" href="../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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>style</em> parameter was added.</p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.format">
|
||
<code class="descname">format</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="#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="#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 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="#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="method">
|
||
<dt id="logging.Formatter.formatTime">
|
||
<code class="descname">formatTime</code><span class="sig-paren">(</span><em>record</em>, <em>datefmt=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Formatter.formatTime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This method should be called from <a class="reference internal" href="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="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="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="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="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="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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="logging.Formatter.formatException">
|
||
<code class="descname">formatException</code><span class="sig-paren">(</span><em>exc_info</em><span class="sig-paren">)</span><a class="headerlink" href="#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="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="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="method">
|
||
<dt id="logging.Formatter.formatStack">
|
||
<code class="descname">formatStack</code><span class="sig-paren">(</span><em>stack_info</em><span class="sig-paren">)</span><a class="headerlink" href="#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="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>
|
||
|
||
</div>
|
||
<div class="section" id="filter-objects">
|
||
<span id="filter"></span><h2>Filter Objects<a class="headerlink" href="#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="class">
|
||
<dt id="logging.Filter">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">Filter</code><span class="sig-paren">(</span><em>name=''</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.Filter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an instance of the <a class="reference internal" href="#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="method">
|
||
<dt id="logging.Filter.filter">
|
||
<code class="descname">filter</code><span class="sig-paren">(</span><em>record</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="#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="#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="#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 LogRecord 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="../howto/logging-cookbook.html#filters-contextual"><span class="std std-ref">Using Filters to impart contextual information</span></a>).</p>
|
||
</div>
|
||
<div class="section" id="logrecord-objects">
|
||
<span id="log-record"></span><h2>LogRecord Objects<a class="headerlink" href="#logrecord-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="reference internal" href="#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="#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="#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="class">
|
||
<dt id="logging.LogRecord">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">LogRecord</code><span class="sig-paren">(</span><em>name</em>, <em>level</em>, <em>pathname</em>, <em>lineno</em>, <em>msg</em>, <em>args</em>, <em>exc_info</em>, <em>func=None</em>, <em>sinfo=None</em><span class="sig-paren">)</span><a class="headerlink" href="#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 <code class="xref py py-attr docutils literal notranslate"><span class="pre">msg</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">args</span></code>, 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> field 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> – The name of the logger used to log the event represented by
|
||
this LogRecord. Note that this name 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> – The numeric level of the logging event (one of DEBUG, INFO etc.)
|
||
Note that this is converted to <em>two</em> attributes of the LogRecord:
|
||
<code class="docutils literal notranslate"><span class="pre">levelno</span></code> for the numeric value and <code class="docutils literal notranslate"><span class="pre">levelname</span></code> for the
|
||
corresponding level name.</p></li>
|
||
<li><p><strong>pathname</strong> – The full pathname of the source file where the logging call
|
||
was made.</p></li>
|
||
<li><p><strong>lineno</strong> – The line number in the source file where the logging call was
|
||
made.</p></li>
|
||
<li><p><strong>msg</strong> – The event description message, possibly a format string with
|
||
placeholders for variable data.</p></li>
|
||
<li><p><strong>args</strong> – Variable data to merge into the <em>msg</em> argument to obtain the
|
||
event description.</p></li>
|
||
<li><p><strong>exc_info</strong> – An exception tuple with the current exception information,
|
||
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> – The name of the function or method from which the logging call
|
||
was invoked.</p></li>
|
||
<li><p><strong>sinfo</strong> – 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="method">
|
||
<dt id="logging.LogRecord.getMessage">
|
||
<code class="descname">getMessage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.LogRecord.getMessage" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the message for this <a class="reference internal" href="#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="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 <code class="docutils literal notranslate"><span class="pre">LogRecord</span></code> 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="#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="#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
|
||
LogRecord at creation time. You can use the following pattern:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">old_factory</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogRecordFactory</span><span class="p">()</span>
|
||
|
||
<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>
|
||
|
||
</div>
|
||
<div class="section" id="logrecord-attributes">
|
||
<span id="id2"></span><h2>LogRecord attributes<a class="headerlink" href="#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="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="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="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>
|
||
<table class="docutils align-center">
|
||
<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="#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="#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="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
|
||
(<code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code>).</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="#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="#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="../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 class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.1: </span><em>processName</em> was added.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="loggeradapter-objects">
|
||
<span id="logger-adapter"></span><h2>LoggerAdapter Objects<a class="headerlink" href="#loggeradapter-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p><a class="reference internal" href="#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="../howto/logging-cookbook.html#context-info"><span class="std std-ref">adding contextual information to your logging output</span></a>.</p>
|
||
<dl class="class">
|
||
<dt id="logging.LoggerAdapter">
|
||
<em class="property">class </em><code class="descclassname">logging.</code><code class="descname">LoggerAdapter</code><span class="sig-paren">(</span><em>logger</em>, <em>extra</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.LoggerAdapter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an instance of <a class="reference internal" href="#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="#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="method">
|
||
<dt id="logging.LoggerAdapter.process">
|
||
<code class="descname">process</code><span class="sig-paren">(</span><em>msg</em>, <em>kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#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>
|
||
|
||
</dd></dl>
|
||
|
||
<p>In addition to the above, <a class="reference internal" href="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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="#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>
|
||
<div class="section" id="thread-safety">
|
||
<h2>Thread Safety<a class="headerlink" href="#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="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="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>
|
||
</div>
|
||
<div class="section" id="module-level-functions">
|
||
<h2>Module-Level Functions<a class="headerlink" href="#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="function">
|
||
<dt id="logging.getLogger">
|
||
<code class="descclassname">logging.</code><code class="descname">getLogger</code><span class="sig-paren">(</span><em>name=None</em><span class="sig-paren">)</span><a class="headerlink" href="#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="function">
|
||
<dt id="logging.getLoggerClass">
|
||
<code class="descclassname">logging.</code><code class="descname">getLoggerClass</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLoggerClass" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return either the standard <a class="reference internal" href="#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="#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="#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"><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="function">
|
||
<dt id="logging.getLogRecordFactory">
|
||
<code class="descclassname">logging.</code><code class="descname">getLogRecordFactory</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="#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="#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="#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="function">
|
||
<dt id="logging.debug">
|
||
<code class="descclassname">logging.</code><code class="descname">debug</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.debug" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> 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="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="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"><pre><span></span><span class="n">FORMAT</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%(asctime)-15s</span><span class="s1"> </span><span class="si">%(clientip)s</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="#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="#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="#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="#logging.Handler" title="logging.Handler"><code class="xref py py-class docutils literal notranslate"><span class="pre">Handler</span></code></a>s.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>The <em>stack_info</em> parameter was added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.info">
|
||
<code class="descclassname">logging.</code><code class="descname">info</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.info" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> on the root logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="function">
|
||
<dt id="logging.warning">
|
||
<code class="descclassname">logging.</code><code class="descname">warning</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.warning" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code> on the root logger. The arguments
|
||
are interpreted as for <a class="reference internal" href="#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="function">
|
||
<dt id="logging.error">
|
||
<code class="descclassname">logging.</code><code class="descname">error</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> on the root logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="function">
|
||
<dt id="logging.critical">
|
||
<code class="descclassname">logging.</code><code class="descname">critical</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.critical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code> on the root logger. The arguments
|
||
are interpreted as for <a class="reference internal" href="#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="function">
|
||
<dt id="logging.exception">
|
||
<code class="descclassname">logging.</code><code class="descname">exception</code><span class="sig-paren">(</span><em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.exception" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Logs a message with level <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code> on the root logger. The arguments are
|
||
interpreted as for <a class="reference internal" href="#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="function">
|
||
<dt id="logging.log">
|
||
<code class="descclassname">logging.</code><code class="descname">log</code><span class="sig-paren">(</span><em>level</em>, <em>msg</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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>The above module-level convenience functions, which delegate to the
|
||
root logger, call <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a> to ensure that at least one handler
|
||
is available. Because of this, they should <em>not</em> be used in threads,
|
||
in versions of Python earlier than 2.7.1 and 3.2, unless at least one
|
||
handler has been added to the root logger <em>before</em> the threads are
|
||
started. In earlier versions of Python, due to a thread safety shortcoming
|
||
in <a class="reference internal" href="#logging.basicConfig" title="logging.basicConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">basicConfig()</span></code></a>, this can (under rare circumstances) lead to
|
||
handlers being added multiple times to the root logger, which can in turn
|
||
lead to multiple messages for the same event.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.disable">
|
||
<code class="descclassname">logging.</code><code class="descname">disable</code><span class="sig-paren">(</span><em>lvl=CRITICAL</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.disable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Provides an overriding level <em>lvl</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>lvl</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>lvl</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>lvl</em> parameter was defaulted to level <code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code>. See Issue
|
||
#28524 for more information about this change.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.addLevelName">
|
||
<code class="descclassname">logging.</code><code class="descname">addLevelName</code><span class="sig-paren">(</span><em>lvl</em>, <em>levelName</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.addLevelName" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Associates level <em>lvl</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="#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="../howto/logging.html#custom-levels"><span class="std std-ref">Custom Levels</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.getLevelName">
|
||
<code class="descclassname">logging.</code><code class="descname">getLevelName</code><span class="sig-paren">(</span><em>lvl</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.getLevelName" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the textual representation of logging level <em>lvl</em>. If the level is one
|
||
of the predefined levels <code class="xref py py-const docutils literal notranslate"><span class="pre">CRITICAL</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ERROR</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">INFO</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">DEBUG</span></code> then you get the corresponding string. If you
|
||
have associated levels with names using <a class="reference internal" href="#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>lvl</em> is returned. If a numeric value corresponding to one
|
||
of the defined levels is passed in, the corresponding string representation is
|
||
returned. Otherwise, the string ‘Level %s’ % lvl 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="#logrecord-attributes"><span class="std std-ref">LogRecord attributes</span></a>).</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="function">
|
||
<dt id="logging.makeLogRecord">
|
||
<code class="descclassname">logging.</code><code class="descname">makeLogRecord</code><span class="sig-paren">(</span><em>attrdict</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.makeLogRecord" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates and returns a new <a class="reference internal" href="#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="#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="#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="function">
|
||
<dt id="logging.basicConfig">
|
||
<code class="descclassname">logging.</code><code class="descname">basicConfig</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#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="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="#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="#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="#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="#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="#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="#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="#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 for it.</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>
|
||
<table class="docutils align-center">
|
||
<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 FileHandler be created,
|
||
using the specified filename, rather than a
|
||
StreamHandler.</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="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.</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="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="stdtypes.html#old-string-formatting"><span class="std std-ref">printf-style</span></a>,
|
||
<a class="reference internal" href="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="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="#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
|
||
StreamHandler. 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>
|
||
</tbody>
|
||
</table>
|
||
<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>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.shutdown">
|
||
<code class="descclassname">logging.</code><code class="descname">shutdown</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#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>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.setLoggerClass">
|
||
<code class="descclassname">logging.</code><code class="descname">setLoggerClass</code><span class="sig-paren">(</span><em>klass</em><span class="sig-paren">)</span><a class="headerlink" href="#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 <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> such that only a name argument is
|
||
required, and the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> 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="#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="function">
|
||
<dt id="logging.setLogRecordFactory">
|
||
<code class="descclassname">logging.</code><code class="descname">setLogRecordFactory</code><span class="sig-paren">(</span><em>factory</em><span class="sig-paren">)</span><a class="headerlink" href="#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="#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="#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="#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="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>
|
||
|
||
</div>
|
||
<div class="section" id="module-level-attributes">
|
||
<h2>Module-Level Attributes<a class="headerlink" href="#module-level-attributes" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="attribute">
|
||
<dt id="logging.lastResort">
|
||
<code class="descclassname">logging.</code><code class="descname">lastResort</code><a class="headerlink" href="#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="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>
|
||
|
||
</div>
|
||
<div class="section" id="integration-with-the-warnings-module">
|
||
<h2>Integration with the warnings module<a class="headerlink" href="#integration-with-the-warnings-module" title="Permalink to this headline">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#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="#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="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="function">
|
||
<dt id="logging.captureWarnings">
|
||
<code class="descclassname">logging.</code><code class="descname">captureWarnings</code><span class="sig-paren">(</span><em>capture</em><span class="sig-paren">)</span><a class="headerlink" href="#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="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="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 <code class="xref py py-const docutils literal notranslate"><span class="pre">WARNING</span></code>.</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="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="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://www.python.org/dev/peps/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://www.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="#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="#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>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><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="#logger-objects">Logger Objects</a></li>
|
||
<li><a class="reference internal" href="#logging-levels">Logging Levels</a></li>
|
||
<li><a class="reference internal" href="#handler-objects">Handler Objects</a></li>
|
||
<li><a class="reference internal" href="#formatter-objects">Formatter Objects</a></li>
|
||
<li><a class="reference internal" href="#filter-objects">Filter Objects</a></li>
|
||
<li><a class="reference internal" href="#logrecord-objects">LogRecord Objects</a></li>
|
||
<li><a class="reference internal" href="#logrecord-attributes">LogRecord attributes</a></li>
|
||
<li><a class="reference internal" href="#loggeradapter-objects">LoggerAdapter Objects</a></li>
|
||
<li><a class="reference internal" href="#thread-safety">Thread Safety</a></li>
|
||
<li><a class="reference internal" href="#module-level-functions">Module-Level Functions</a></li>
|
||
<li><a class="reference internal" href="#module-level-attributes">Module-Level Attributes</a></li>
|
||
<li><a class="reference internal" href="#integration-with-the-warnings-module">Integration with the warnings module</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="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>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="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 role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/logging.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.config.html" title="logging.config — Logging configuration"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="getopt.html" title="getopt — C-style parser for command line options"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" >Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |