688 lines
86 KiB
HTML
688 lines
86 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>logging.config --- 日志记录配置 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="logging.handlers --- 日志处理程序" href="logging.handlers.html" />
|
||
<link rel="prev" title="logging --- Python 的日志记录工具" href="logging.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/logging.config.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code> --- 日志记录配置</a><ul>
|
||
<li><a class="reference internal" href="#configuration-functions">配置函数</a></li>
|
||
<li><a class="reference internal" href="#configuration-dictionary-schema">配置字典架构</a><ul>
|
||
<li><a class="reference internal" href="#dictionary-schema-details">字典架构细节</a></li>
|
||
<li><a class="reference internal" href="#incremental-configuration">增量配置</a></li>
|
||
<li><a class="reference internal" href="#object-connections">对象连接</a></li>
|
||
<li><a class="reference internal" href="#user-defined-objects">用户定义对象</a></li>
|
||
<li><a class="reference internal" href="#access-to-external-objects">访问外部对象</a></li>
|
||
<li><a class="reference internal" href="#access-to-internal-objects">访问内部对象</a></li>
|
||
<li><a class="reference internal" href="#import-resolution-and-custom-importers">导入解析与定制导入器</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#configuration-file-format">配置文件格式</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="logging.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> --- Python 的日志记录工具</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="logging.handlers.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.handlers</span></code> --- 日志处理程序</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/logging.config.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/logging.config.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.handlers.html" title="logging.handlers --- 日志处理程序"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.html" title="logging --- Python 的日志记录工具"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">通用操作系统服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-logging.config">
|
||
<span id="logging-config-logging-configuration"></span><h1><a class="reference internal" href="#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> --- 日志记录配置<a class="headerlink" href="#module-logging.config" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码：</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/logging/config.py">Lib/logging/config.py</a></p>
|
||
<aside class="sidebar">
|
||
<p class="sidebar-title">Important</p>
|
||
<p>此页面仅包含参考信息。有关教程，请参阅</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="../howto/logging.html#logging-basic-tutorial"><span class="std std-ref">基础教程</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging.html#logging-advanced-tutorial"><span class="std std-ref">进阶教程</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../howto/logging-cookbook.html#logging-cookbook"><span class="std std-ref">日志记录操作手册</span></a></p></li>
|
||
</ul>
|
||
</aside>
|
||
<hr class="docutils" />
|
||
<p>这一节描述了用于配置 logging 模块的 API。</p>
|
||
<section id="configuration-functions">
|
||
<span id="logging-config-api"></span><h2>配置函数<a class="headerlink" href="#configuration-functions" title="永久链接至标题">¶</a></h2>
|
||
<p>下列函数可配置 logging 模块。 它们位于 <a class="reference internal" href="#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> 模块中。 它们的使用是可选的 --- 要配置 logging 模块你可以使用这些函数，也可以通过调用主 API (在 <a class="reference internal" href="logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 本身定义) 并定义在 <a class="reference internal" href="logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 或 <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>
|
||
<dl class="function">
|
||
<dt id="logging.config.dictConfig">
|
||
<code class="sig-prename descclassname">logging.config.</code><code class="sig-name descname">dictConfig</code><span class="sig-paren">(</span><em class="sig-param">config</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.config.dictConfig" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从一个字典获取日志记录配置。 字典的内容描述见下文的 <a class="reference internal" href="#logging-config-dictschema"><span class="std std-ref">配置字典架构</span></a>。</p>
|
||
<p>如果在配置期间遇到错误，此函数将引发 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>, <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> 或 <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> 并附带适当的描述性消息。 下面是将会引发错误的（可能不完整的）条件列表:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">level</span></code> 不是字符串或者不是对应于实际日志记录级别的字符串。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">propagate</span></code> 值不是布尔类型。</p></li>
|
||
<li><p>id 没有对应的目标。</p></li>
|
||
<li><p>在增量调用期间发现不存在的处理器 id。</p></li>
|
||
<li><p>无效的日志记录器名称。</p></li>
|
||
<li><p>无法解析为内部或外部对象。</p></li>
|
||
</ul>
|
||
<p>解析由 <code class="xref py py-class docutils literal notranslate"><span class="pre">DictConfigurator</span></code> 类执行，该类的构造器可传入用于配置的字典，并且具有 <code class="xref py py-meth docutils literal notranslate"><span class="pre">configure()</span></code> 方法。 <a class="reference internal" href="#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> 模块具有可调用属性 <code class="xref py py-attr docutils literal notranslate"><span class="pre">dictConfigClass</span></code>，其初始值设为 <code class="xref py py-class docutils literal notranslate"><span class="pre">DictConfigurator</span></code>。 你可以使用你自己的适当实现来替换 <code class="xref py py-attr docutils literal notranslate"><span class="pre">dictConfigClass</span></code> 的值。</p>
|
||
<p><a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> 会调用 <code class="xref py py-attr docutils literal notranslate"><span class="pre">dictConfigClass</span></code> 并传入指定的字典，然后在所返回的对象上调用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">configure()</span></code> 方法以使配置生效:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dictConfig</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>
|
||
<span class="n">dictConfigClass</span><span class="p">(</span><span class="n">config</span><span class="p">)</span><span class="o">.</span><span class="n">configure</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>例如，<code class="xref py py-class docutils literal notranslate"><span class="pre">DictConfigurator</span></code> 的子类可以在它自己的 <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> 中调用 <code class="docutils literal notranslate"><span class="pre">DictConfigurator.__init__()</span></code>，然后设置可以在后续 <code class="xref py py-meth docutils literal notranslate"><span class="pre">configure()</span></code> 调用中使用的自定义前缀。 <code class="xref py py-attr docutils literal notranslate"><span class="pre">dictConfigClass</span></code> 将被绑定到这个新的子类，然后就可以与在默认的未定制状态下完全相同的方式调用 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a>。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.config.fileConfig">
|
||
<code class="sig-prename descclassname">logging.config.</code><code class="sig-name descname">fileConfig</code><span class="sig-paren">(</span><em class="sig-param">fname</em>, <em class="sig-param">defaults=None</em>, <em class="sig-param">disable_existing_loggers=True</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.config.fileConfig" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从一个 <a class="reference internal" href="configparser.html#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> 格式文件中读取日志记录配置。 文件格式应当与 <a class="reference internal" href="#logging-config-fileformat"><span class="std std-ref">配置文件格式</span></a> 中的描述一致。 此函数可在应用程序中被多次调用，以允许最终用户在多个预设配置中进行选择（如果开发者提供了展示选项并加载选定配置的机制）。</p>
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">参数</dt>
|
||
<dd class="field-odd"><ul class="simple">
|
||
<li><p><strong>fname</strong> -- 一个文件名，或一个文件类对象，或是一个派生自 <a class="reference internal" href="configparser.html#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> 的实例。 如果传入了一个派生自 <code class="docutils literal notranslate"><span class="pre">RawConfigParser</span></code> 的实例，它会被原样使用。 否则，将会实例化一个 <code class="xref py py-class docutils literal notranslate"><span class="pre">Configparser</span></code>，并且它会从作为 <code class="docutils literal notranslate"><span class="pre">fname</span></code> 传入的对象中读取配置。 如果存在 <a class="reference internal" href="readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> 方法，则它会被当作一个文件类对象并使用 <a class="reference internal" href="configparser.html#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code></a> 来读取；在其它情况下，它会被当作一个文件名并传递给 <a class="reference internal" href="configparser.html#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a>。</p></li>
|
||
<li><p><strong>defaults</strong> -- 要传递给 ConfigParser 的默认值可在此参数中指定。</p></li>
|
||
<li><p><strong>disable_existing_loggers</strong> -- 如果指定为 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则当执行此调用时已存在的日志记录器会保持启用。 默认值为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 因为这将以向下兼容方式启用旧行为。 此行为是禁用任何现有的非根日志记录器除非它们或它们的上级在日志记录配置中被显式地命名。</p></li>
|
||
</ul>
|
||
</dd>
|
||
</dl>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.4 版更改: </span>现在接受 <a class="reference internal" href="configparser.html#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> 子类的实例作为 <code class="docutils literal notranslate"><span class="pre">fname</span></code> 的值。 这有助于:</p>
|
||
<ul class="simple">
|
||
<li><p>使用一个配置文件，其中日志记录配置只是全部应用程序配置的一部分。</p></li>
|
||
<li><p>使用从一个文件读取的配置，它随后会在被传给 <code class="docutils literal notranslate"><span class="pre">fileConfig</span></code> 之前由使用配置的应用程序来修改（例如基于命令行参数或运行时环境的其他部分）。</p></li>
|
||
</ul>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.config.listen">
|
||
<code class="sig-prename descclassname">logging.config.</code><code class="sig-name descname">listen</code><span class="sig-paren">(</span><em class="sig-param">port=DEFAULT_LOGGING_CONFIG_PORT</em>, <em class="sig-param">verify=None</em><span class="sig-paren">)</span><a class="headerlink" href="#logging.config.listen" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在指定的端口上启动套接字服务器，并监听新的配置。 如果未指定端口，则会使用模块默认的 <code class="xref py py-const docutils literal notranslate"><span class="pre">DEFAULT_LOGGING_CONFIG_PORT</span></code>。 日志记录配置将作为适合由 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> 或 <a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> 进行处理的文件来发送。 返回一个 <a class="reference internal" href="threading.html#threading.Thread" title="threading.Thread"><code class="xref py py-class docutils literal notranslate"><span class="pre">Thread</span></code></a> 实例，你可以在该实例上调用 <a class="reference internal" href="threading.html#threading.Thread.start" title="threading.Thread.start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code></a> 来启动服务器，对该服务器你可以在适当的时候执行 <a class="reference internal" href="threading.html#threading.Thread.join" title="threading.Thread.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>。 要停止该服务器，请调用 <a class="reference internal" href="#logging.config.stopListening" title="logging.config.stopListening"><code class="xref py py-func docutils literal notranslate"><span class="pre">stopListening()</span></code></a>。</p>
|
||
<p>如果指定 <code class="docutils literal notranslate"><span class="pre">verify</span></code> 参数，则它应当是一个可调用对象，该对象应当验证通过套接字接收的字节数据是否有效且应被处理。 这可以通过对通过套接字发送的内容进行加密和/或签名来完成，这样 <code class="docutils literal notranslate"><span class="pre">verify</span></code> 可调用对象就能执行签名验证和/或解密。 <code class="docutils literal notranslate"><span class="pre">verify</span></code> 可调用对象的调用会附带一个参数 —— 通过套接字接收的字节数据 —— 并应当返回要处理的字节数据，或者返回 <code class="docutils literal notranslate"><span class="pre">None</span></code> 来指明这些字节数据应当被丢弃。 返回的字节数据可以与传入的字节数据相同（例如在只执行验证的时候），或者也可以完全不同（例如在可能执行了解密的时候）。</p>
|
||
<p>要将配置发送到套接字，请读取配置文件并将其作为字节序列发送到套接字，字节序列要以使用 <code class="docutils literal notranslate"><span class="pre">struct.pack('>L',</span> <span class="pre">n)</span></code> 打包为二进制格式的四字节长度的字符串打头。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>因为配置的各部分是通过 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> 传递的，使用此函数可能让用户面临安全风险。 虽然此函数仅绑定到 <code class="docutils literal notranslate"><span class="pre">localhost</span></code> 上的套接字，因此并不接受来自远端机器的连接，但在某些场景中不受信任的代码可以在调用 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 的进程的账户下运行。 具体来说，如果如果调用 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 的进程在用户无法彼此信任的多用户机器上运行，则恶意用户就能简单地通过连接到受害者的 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 套接字并发送运行攻击者想在受害者的进程上执行的任何代码的配置的方式，安排运行几乎任意的代码。 如果是使用默认端口这会特别容易做到，即便使用了不同端口也不难做到。 要避免发生这种情况的风险，请在 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 中使用 <code class="docutils literal notranslate"><span class="pre">verify</span></code> 参数来防止未经认可的配置被应用。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.4 版更改: </span>添加了 <code class="docutils literal notranslate"><span class="pre">verify</span></code> 参数。</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>如果你希望将配置发送给未禁用现有日志记录器的监听器，你将需要使用 JSON 格式的配置，该格式将使用 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> 进行配置。 此方法允许你在你发送的配置中将 <code class="docutils literal notranslate"><span class="pre">disable_existing_loggers</span></code> 指定为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="logging.config.stopListening">
|
||
<code class="sig-prename descclassname">logging.config.</code><code class="sig-name descname">stopListening</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#logging.config.stopListening" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>停止通过对 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 的调用所创建的监听服务器。 此函数的调用通常会先于在 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 的返回值上调用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="configuration-dictionary-schema">
|
||
<span id="logging-config-dictschema"></span><h2>配置字典架构<a class="headerlink" href="#configuration-dictionary-schema" title="永久链接至标题">¶</a></h2>
|
||
<p>描述日志记录配置需要列出要创建的不同对象及它们之间的连接；例如，你可以创建一个名为 'console' 的处理器，然后名为 'startup' 的日志记录器将可以把它的消息发送给 'console' 处理器。 这些对象并不仅限于 <a class="reference internal" href="logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 模块所提供的对象，因为你还可以编写你自己的格式化或处理器类。 这些类的形参可能还需要包括 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> 这样的外部对象。 描述这些对象和连接的语法会在下面的 <a class="reference internal" href="#logging-config-dict-connections"><span class="std std-ref">对象连接</span></a> 中定义。</p>
|
||
<section id="dictionary-schema-details">
|
||
<h3>字典架构细节<a class="headerlink" href="#dictionary-schema-details" title="永久链接至标题">¶</a></h3>
|
||
<p>传给 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> 的字典必须包含以下的键:</p>
|
||
<ul class="simple">
|
||
<li><p><em>version</em> - 应设为代表架构版本的整数值。 目前唯一有效的值是 1，使用此键可允许架构在继续演化的同时保持向下兼容性。</p></li>
|
||
</ul>
|
||
<p>所有其他键都是可选项，但如存在它们将根据下面的描述来解读。 在下面提到 'configuring dict' 的所有情况下，都将检查它的特殊键 <code class="docutils literal notranslate"><span class="pre">'()'</span></code> 以确定是否需要自定义实例化。 如果需要，则会使用下面 <a class="reference internal" href="#logging-config-dict-userdef"><span class="std std-ref">用户定义对象</span></a> 所描述的机制来创建一个实例；否则，会使用上下文来确定要实例化的对象。</p>
|
||
<ul>
|
||
<li><p><em>formatters</em> - 对应的值将是一个字典，其中每个键是一个格式器 ID 而每个值则是一个描述如何配置相应 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 实例的字典。</p>
|
||
<p>将在配置字典中搜索键 <code class="docutils literal notranslate"><span class="pre">format</span></code> 和 <code class="docutils literal notranslate"><span class="pre">datefmt</span></code> (默认值均为 <code class="docutils literal notranslate"><span class="pre">None</span></code>) 并且这些键会被用于构造 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 实例。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>一个 <code class="docutils literal notranslate"><span class="pre">validate</span></code> 键 (默认值为 <code class="docutils literal notranslate"><span class="pre">True</span></code>) 可被添加到配置字典的 <code class="docutils literal notranslate"><span class="pre">formatters</span></code> 部分，这会被用来验证格式的有效性。</p>
|
||
</div>
|
||
</li>
|
||
<li><p><em>filters</em> - 对应的值将是一个字典，其中每个键是一个过滤器 ID 而每个值则是一个描述如何配置相应 Filter 实例的字典。</p>
|
||
<p>将在配置字典中搜索键 <code class="docutils literal notranslate"><span class="pre">name</span></code> (默认值为空字符串) 并且该键会被用于构造 <a class="reference internal" href="logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.Filter</span></code></a> 实例。</p>
|
||
</li>
|
||
<li><p><em>handlers</em> - 对应的值将是一个字典，其中每个键是一个处理器 ID 而每个值则是一个描述如何配置相应 Handler 实例的字典。</p>
|
||
<p>将在配置字典中搜索下列键:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">class</span></code> (强制)。 这是处理器类的完整限定名称。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">level</span></code> (可选)。 处理器的级别。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">formatter</span></code> (可选)。 处理器所对应格式化器的 ID。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">filters</span></code> (可选)。 由处理器所对应过滤器的 ID 组成的列表。</p></li>
|
||
</ul>
|
||
<p>所有 <em>其他</em> 键会被作为关键字参数传递给处理器类的构造器。 例如，给定如下配置:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">handlers</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">console</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">class </span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">logging.StreamHandler</span>
|
||
<span class="w"> </span><span class="nt">formatter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">brief</span>
|
||
<span class="w"> </span><span class="nt">level </span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">INFO</span>
|
||
<span class="w"> </span><span class="nt">filters</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">allow_foo</span><span class="p p-Indicator">]</span>
|
||
<span class="w"> </span><span class="nt">stream </span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ext://sys.stdout</span>
|
||
<span class="w"> </span><span class="nt">file</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">class </span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">logging.handlers.RotatingFileHandler</span>
|
||
<span class="w"> </span><span class="nt">formatter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">precise</span>
|
||
<span class="w"> </span><span class="nt">filename</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">logconfig.log</span>
|
||
<span class="w"> </span><span class="nt">maxBytes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1024</span>
|
||
<span class="w"> </span><span class="nt">backupCount</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>ID 为 <code class="docutils literal notranslate"><span class="pre">console</span></code> 的处理器会被实例化为 <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">logging.StreamHandler</span></code></a>，并使用 <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> 作为下层流。 ID 为 <code class="docutils literal notranslate"><span class="pre">file</span></code> 的处理器会被实例化为 <a class="reference internal" href="logging.handlers.html#logging.handlers.RotatingFileHandler" title="logging.handlers.RotatingFileHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.handlers.RotatingFileHandler</span></code></a>，并附带关键字参数 <code class="docutils literal notranslate"><span class="pre">filename='logconfig.log',</span> <span class="pre">maxBytes=1024,</span> <span class="pre">backupCount=3</span></code>。</p>
|
||
</li>
|
||
<li><p><em>loggers</em> - 对应的值将是一个字典，其中每个键是一个日志记录器名称而每个值则是一个描述如何配置相应 Logger 实例的字典。</p>
|
||
<p>将在配置字典中搜索下列键:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">level</span></code> (可选)。 日志记录器的级别。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">propagate</span></code> (可选)。 日志记录器的传播设置。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">filters</span></code> (可选)。 由日志记录器对应过滤器的 ID 组成的列表。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">handlers</span></code> (可选)。 由日志记录器对应处理器的 ID 组成的列表。</p></li>
|
||
</ul>
|
||
<p>指定的记录器将根据指定的级别、传播、过滤器和处理器来配置。</p>
|
||
</li>
|
||
<li><p><em>root</em> - 这将成为根日志记录器对应的配置。 配置的处理方式将与所有日志记录器一致，除了 <code class="docutils literal notranslate"><span class="pre">propagate</span></code> 设置将不可用之外。</p></li>
|
||
<li><p><em>incremental</em> - 配置是否要被解读为在现有配置上新增。 该值默认为 <code class="docutils literal notranslate"><span class="pre">False</span></code>，这意味着指定的配置将以与当前 <a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> API 所使用的相同语义来替代现有的配置。</p>
|
||
<p>如果指定的值为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，配置会按照 <a class="reference internal" href="#logging-config-dict-incremental"><span class="std std-ref">增量配置</span></a> 部分所描述的方式来处理。</p>
|
||
</li>
|
||
<li><p><em>disable_existing_loggers</em> - 是否要禁用任何现有的非根日志记录器。 该设置对应于 <a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> 中的同名形参。 如果省略，则此形参默认为 <code class="docutils literal notranslate"><span class="pre">True</span></code>。 如果 <em>incremental</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 则该省会被忽略。</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="incremental-configuration">
|
||
<span id="logging-config-dict-incremental"></span><h3>增量配置<a class="headerlink" href="#incremental-configuration" title="永久链接至标题">¶</a></h3>
|
||
<p>为增量配置提供完全的灵活性是很困难的。 例如，由于过滤器和格式化器这样的对象是匿名的，一旦完成配置，在增加配置时就不可能引用这些匿名对象。</p>
|
||
<p>此外，一旦完成了配置，在运行时任意改变日志记录器、处理器、过滤器、格式化器的对象图就不是很有必要；日志记录器和处理器的详细程度只需通过设置级别即可实现控制（对于日志记录器则可设置传播旗标）。 在多线程环境中以安全的方式任意改变对象图也许会导致问题；虽然并非不可能，但这样做的好处不足以抵销其所增加的实现复杂度。</p>
|
||
<p>这样，当配置字典的 <code class="docutils literal notranslate"><span class="pre">incremental</span></code> 键存在且为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 时，系统将完全忽略任何 <code class="docutils literal notranslate"><span class="pre">formatters</span></code> 和 <code class="docutils literal notranslate"><span class="pre">filters</span></code> 条目，并仅会处理 <code class="docutils literal notranslate"><span class="pre">handlers</span></code> 条目中的 <code class="docutils literal notranslate"><span class="pre">level</span></code> 设置，以及 <code class="docutils literal notranslate"><span class="pre">loggers</span></code> 和 <code class="docutils literal notranslate"><span class="pre">root</span></code> 条目中的 <code class="docutils literal notranslate"><span class="pre">level</span></code> 和 <code class="docutils literal notranslate"><span class="pre">propagate</span></code> 设置。</p>
|
||
<p>使用配置字典中的值可让配置以封存字典对象的形式通过线路传送给套接字监听器。 这样，长时间运行的应用程序的日志记录的详细程度可随时间改变而无须停止并重新启动应用程序。</p>
|
||
</section>
|
||
<section id="object-connections">
|
||
<span id="logging-config-dict-connections"></span><h3>对象连接<a class="headerlink" href="#object-connections" title="永久链接至标题">¶</a></h3>
|
||
<p>该架构描述了一组日志记录对象 —— 日志记录器、处理器、格式化器、过滤器 —— 它们在对象图中彼此连接。 因此，该架构需要能表示对象之间的连接。 例如，在配置完成后，一个特定的日志记录器关联到了一个特定的处理器。 出于讨论的目的，我们可以说该日志记录器代表两者间连接的源头，而处理器则代表对应的目标。 当然在已配置对象中这是由包含对处理器的引用的日志记录器来代表的。 在配置字典中，这是通过给每个目标对象一个 ID 来无歧义地标识它，然后在源头对象中使用该 ID 来实现的。</p>
|
||
<p>因此，举例来说，考虑以下 YAML 代码段:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">formatters</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">brief</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="c1"># configuration for formatter with id 'brief' goes here</span>
|
||
<span class="w"> </span><span class="nt">precise</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="c1"># configuration for formatter with id 'precise' goes here</span>
|
||
<span class="nt">handlers</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">h1</span><span class="p">:</span><span class="w"> </span><span class="c1">#This is an id</span>
|
||
<span class="w"> </span><span class="c1"># configuration of handler with id 'h1' goes here</span>
|
||
<span class="w"> </span><span class="nt">formatter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">brief</span>
|
||
<span class="w"> </span><span class="nt">h2</span><span class="p">:</span><span class="w"> </span><span class="c1">#This is another id</span>
|
||
<span class="w"> </span><span class="c1"># configuration of handler with id 'h2' goes here</span>
|
||
<span class="w"> </span><span class="nt">formatter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">precise</span>
|
||
<span class="nt">loggers</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">foo.bar.baz</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="c1"># other configuration for logger 'foo.bar.baz'</span>
|
||
<span class="w"> </span><span class="nt">handlers</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">h1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">h2</span><span class="p p-Indicator">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>（注：这里使用 YAML 是因为它的可读性比表示字典的等价 Python 源码形式更好。）</p>
|
||
<p>日志记录器 ID 就是日志记录器的名称，它会在程序中被用来获取对日志记录器的引用，例如 <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>。 格式化器和过滤器的 ID 可以是任意字符串值 (例如上面的 <code class="docutils literal notranslate"><span class="pre">brief</span></code>, <code class="docutils literal notranslate"><span class="pre">precise</span></code>) 并且它们是瞬态的，因为它们仅对处理配置字典有意义并会被用来确定对象之间的连接，而当配置调用完成时不会在任何地方保留。</p>
|
||
<p>上面的代码片段指明名为 <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code> 的日志记录器应当关联到两个处理器，它们的 ID 是 <code class="docutils literal notranslate"><span class="pre">h1</span></code> 和 <code class="docutils literal notranslate"><span class="pre">h2</span></code>。 <code class="docutils literal notranslate"><span class="pre">h1</span></code> 的格式化器的 ID 是 <code class="docutils literal notranslate"><span class="pre">brief</span></code>，而 <code class="docutils literal notranslate"><span class="pre">h2</span></code> 的格式化器的 ID 是 <code class="docutils literal notranslate"><span class="pre">precise</span></code>。</p>
|
||
</section>
|
||
<section id="user-defined-objects">
|
||
<span id="logging-config-dict-userdef"></span><h3>用户定义对象<a class="headerlink" href="#user-defined-objects" title="永久链接至标题">¶</a></h3>
|
||
<p>此架构支持用户定义对象作为处理器、过滤器和格式化器。 （日志记录器的不同实例不需要具有不同类型，因此这个配置架构并不支持用户定义日志记录器类。）</p>
|
||
<p>要配置的对象是由字典描述的，其中包含它们的配置详情。 在某些地方，日志记录系统将能够从上下文中推断出如何实例化一个对象，但是当要实例化一个用户自定义对象时，系统将不知道要如何做。 为了提供用户自定义对象实例化的完全灵活性，用户需要提供一个‘工厂’函数 —— 即在调用时传入配置字典并返回实例化对象的可调用对象。 这是用一个通过特殊键 <code class="docutils literal notranslate"><span class="pre">'()'</span></code> 来访问的工厂函数的绝对导入路径来标示的。 下面是一个实际的例子:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">formatters</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">brief</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="s">'%(message)s'</span>
|
||
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="s">'%(asctime)s</span><span class="nv"> </span><span class="s">%(levelname)-8s</span><span class="nv"> </span><span class="s">%(name)-15s</span><span class="nv"> </span><span class="s">%(message)s'</span>
|
||
<span class="w"> </span><span class="nt">datefmt</span><span class="p">:</span><span class="w"> </span><span class="s">'%Y-%m-%d</span><span class="nv"> </span><span class="s">%H:%M:%S'</span>
|
||
<span class="w"> </span><span class="nt">custom</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">()</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my.package.customFormatterFactory</span>
|
||
<span class="w"> </span><span class="nt">bar</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">baz</span>
|
||
<span class="w"> </span><span class="nt">spam</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">99.9</span>
|
||
<span class="w"> </span><span class="nt">answer</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">42</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>上面的 YAML 代码片段定义了三个格式化器。 第一个的 ID 为 <code class="docutils literal notranslate"><span class="pre">brief</span></code>，是带有特殊格式字符串的标准 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.Formatter</span></code></a> 实例。 第二个的 ID 为 <code class="docutils literal notranslate"><span class="pre">default</span></code>，具有更长的格式同时还显式地定义了时间格式，并将最终实例化一个带有这两个格式字符串的 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.Formatter</span></code></a>。 以 Python 源代码形式显示的 <code class="docutils literal notranslate"><span class="pre">brief</span></code> 和 <code class="docutils literal notranslate"><span class="pre">default</span></code> 格式化器分别具有下列配置子字典:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="s1">'format'</span> <span class="p">:</span> <span class="s1">'</span><span class="si">%(message)s</span><span class="s1">'</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>和:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="s1">'format'</span> <span class="p">:</span> <span class="s1">'</span><span class="si">%(asctime)s</span><span class="s1"> </span><span class="si">%(levelname)-8s</span><span class="s1"> </span><span class="si">%(name)-15s</span><span class="s1"> </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">,</span>
|
||
<span class="s1">'datefmt'</span> <span class="p">:</span> <span class="s1">'%Y-%m-</span><span class="si">%d</span><span class="s1"> %H:%M:%S'</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>并且由于这些字典不包含特殊键 <code class="docutils literal notranslate"><span class="pre">'()'</span></code>，实例化方式是从上下文中推断出来的：结果会创建标准的 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.Formatter</span></code></a> 实例。 第三个格式器的 ID 为 <code class="docutils literal notranslate"><span class="pre">custom</span></code>，对应配置子字典为:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="s1">'()'</span> <span class="p">:</span> <span class="s1">'my.package.customFormatterFactory'</span><span class="p">,</span>
|
||
<span class="s1">'bar'</span> <span class="p">:</span> <span class="s1">'baz'</span><span class="p">,</span>
|
||
<span class="s1">'spam'</span> <span class="p">:</span> <span class="mf">99.9</span><span class="p">,</span>
|
||
<span class="s1">'answer'</span> <span class="p">:</span> <span class="mi">42</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>并且它包含特殊键 <code class="docutils literal notranslate"><span class="pre">'()'</span></code>，这意味着需要用户自定义实例化方式。 在此情况下，将使用指定的工厂可调用对象。 如果它本身就是一个可调用对象则将被直接使用 —— 否则如果你指定了一个字符串（如这个例子所示）则将使用正常的导入机制来定位实例的可调用对象。 调用该可调用对象将传入配置子字典中 <strong>剩余的</strong> 条目作为关键字参数。 在上面的例子中，调用将预期返回 ID 为 <code class="docutils literal notranslate"><span class="pre">custom</span></code> 的格式化器:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">my</span><span class="o">.</span><span class="n">package</span><span class="o">.</span><span class="n">customFormatterFactory</span><span class="p">(</span><span class="n">bar</span><span class="o">=</span><span class="s1">'baz'</span><span class="p">,</span> <span class="n">spam</span><span class="o">=</span><span class="mf">99.9</span><span class="p">,</span> <span class="n">answer</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>将 <code class="docutils literal notranslate"><span class="pre">'()'</span></code> 用作特殊键是因为它不是一个有效的关键字形参名称，这样就不会与调用中使用的关键字参数发生冲突。 <code class="docutils literal notranslate"><span class="pre">'()'</span></code> 还被用作表明对应值为可调用对象的助记符。</p>
|
||
</section>
|
||
<section id="access-to-external-objects">
|
||
<span id="logging-config-dict-externalobj"></span><h3>访问外部对象<a class="headerlink" href="#access-to-external-objects" title="永久链接至标题">¶</a></h3>
|
||
<p>有时一个配置需要引用配置以外的对象，例如 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>。 如果配置字典是使用 Python 代码构造的，这会很直观，但是当配置是通过文本文件（例如 JSON, YAML）提供的时候就会引发问题。 在一个文本文件中，没有将 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> 与字符串字面值 <code class="docutils literal notranslate"><span class="pre">'sys.stderr'</span></code> 区分开来的标准方式。 为了实现这种区分，配置系统会在字符串值中查找规定的特殊前缀并对其做特殊处理。 例如，如果在配置中将字符串字面值 <code class="docutils literal notranslate"><span class="pre">'ext://sys.stderr'</span></code> 作为一个值来提供，则 <code class="docutils literal notranslate"><span class="pre">ext://</span></code> 将被去除而该值的剩余部分将使用正常导入机制来处理。</p>
|
||
<p>此类前缀的处理方式类似于协议处理：存在一种通用机制来查找与正则表达式 <code class="docutils literal notranslate"><span class="pre">^(?P<prefix>[a-z]+)://(?P<suffix>.*)$</span></code> 相匹配的前缀，如果识别出了 <code class="docutils literal notranslate"><span class="pre">prefix</span></code>，则 <code class="docutils literal notranslate"><span class="pre">suffix</span></code> 会以与前缀相对应的方式来处理并且处理的结果将替代原字符串值。 如果未识别出前缀，则原字符串将保持不变。</p>
|
||
</section>
|
||
<section id="access-to-internal-objects">
|
||
<span id="logging-config-dict-internalobj"></span><h3>访问内部对象<a class="headerlink" href="#access-to-internal-objects" title="永久链接至标题">¶</a></h3>
|
||
<p>除了外部对象，有时还需要引用配置中的对象。 这将由配置系统针对它所了解的内容隐式地完成。 例如，在日志记录器或处理器中表示 <code class="docutils literal notranslate"><span class="pre">level</span></code> 的字符串值 <code class="docutils literal notranslate"><span class="pre">'DEBUG'</span></code> 将被自动转换为值 <code class="docutils literal notranslate"><span class="pre">logging.DEBUG</span></code>，而 <code class="docutils literal notranslate"><span class="pre">handlers</span></code>, <code class="docutils literal notranslate"><span class="pre">filters</span></code> 和 <code class="docutils literal notranslate"><span class="pre">formatter</span></code> 条目将接受一个对象 ID 并解析为适当的目标对象。</p>
|
||
<p>但是，对于 <a class="reference internal" href="logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a> 模块所不了解的用户自定义对象则需要一种更通用的机制。 例如，考虑 <a class="reference internal" href="logging.handlers.html#logging.handlers.MemoryHandler" title="logging.handlers.MemoryHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">logging.handlers.MemoryHandler</span></code></a>，它接受一个 <code class="docutils literal notranslate"><span class="pre">target</span></code> 参数即其所委托的另一个处理器。 由于系统已经知道存在该类，因而在配置中，给定的 <code class="docutils literal notranslate"><span class="pre">target</span></code> 只需为相应目标处理器的的对象 ID 即可，而系统将根据该 ID 解析出处理器。 但是，如果用户定义了一个具有 <code class="docutils literal notranslate"><span class="pre">alternate</span></code> 处理器的 <code class="docutils literal notranslate"><span class="pre">my.package.MyHandler</span></code>，则配置程序将不知道 <code class="docutils literal notranslate"><span class="pre">alternate</span></code> 指向的是一个处理器。 为了应对这种情况，通用解析系统允许用户指定:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">handlers</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">file</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="c1"># configuration of file handler goes here</span>
|
||
|
||
<span class="w"> </span><span class="nt">custom</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">()</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my.package.MyHandler</span>
|
||
<span class="w"> </span><span class="nt">alternate</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cfg://handlers.file</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>字符串字面值 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.file'</span></code> 将按照与 <code class="docutils literal notranslate"><span class="pre">ext://</span></code> 前缀类似的方式被解析为结果字符串，但查找操作是在配置自身而不是在导入命名空间中进行。 该机制允许按点号或按索引来访问，与 <code class="docutils literal notranslate"><span class="pre">str.format</span></code> 所提供的方式类似。 这样，给定以下代码段:</p>
|
||
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">handlers</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">email</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="nt">class</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">logging.handlers.SMTPHandler</span>
|
||
<span class="w"> </span><span class="nt">mailhost</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
|
||
<span class="w"> </span><span class="nt">fromaddr</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_app@domain.tld</span>
|
||
<span class="w"> </span><span class="nt">toaddrs</span><span class="p">:</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">support_team@domain.tld</span>
|
||
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dev_team@domain.tld</span>
|
||
<span class="w"> </span><span class="nt">subject</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Houston, we have a problem.</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在该配置中，字符串 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers'</span></code> 将解析为带有 <code class="docutils literal notranslate"><span class="pre">handlers</span></code> 键的字典，字符串 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.email</span></code> 将解析为 <code class="docutils literal notranslate"><span class="pre">handlers</span></code> 字典中带有 <code class="docutils literal notranslate"><span class="pre">email</span></code> 键的字典，依此类推。 字符串 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.email.toaddrs[1]</span></code> 将解析为 <code class="docutils literal notranslate"><span class="pre">'dev_team.domain.tld'</span></code> 而字符串 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.email.toaddrs[0]'</span></code> 将解析为值 <code class="docutils literal notranslate"><span class="pre">'support_team@domain.tld'</span></code>。 <code class="docutils literal notranslate"><span class="pre">subject</span></code> 值可以使用 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.email.subject'</span></code> 或者等价的 <code class="docutils literal notranslate"><span class="pre">'cfg://handlers.email[subject]'</span></code> 来访问。 后一种形式仅在键包含空格或非字母数字类字符的情况下才需要使用。 如果一个索引仅由十进制数码构成，则将尝试使用相应的整数值来访问，如果有必要则将回退为字符串值。</p>
|
||
<p>给定字符串 <code class="docutils literal notranslate"><span class="pre">cfg://handlers.myhandler.mykey.123</span></code>，这将解析为 <code class="docutils literal notranslate"><span class="pre">config_dict['handlers']['myhandler']['mykey']['123']</span></code>。 如果字符串被指定为 <code class="docutils literal notranslate"><span class="pre">cfg://handlers.myhandler.mykey[123]</span></code>，系统将尝试从 <code class="docutils literal notranslate"><span class="pre">config_dict['handlers']['myhandler']['mykey'][123]</span></code> 中提取值，并在尝试失败时回退为 <code class="docutils literal notranslate"><span class="pre">config_dict['handlers']['myhandler']['mykey']['123']</span></code>。</p>
|
||
</section>
|
||
<section id="import-resolution-and-custom-importers">
|
||
<span id="logging-import-resolution"></span><h3>导入解析与定制导入器<a class="headerlink" href="#import-resolution-and-custom-importers" title="永久链接至标题">¶</a></h3>
|
||
<p>导入解析默认使用内置的 <a class="reference internal" href="functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> 函数来执行导入。 你可能想要将其替换为你自己的导入机制：如果是这样的话，你可以替换 <code class="xref py py-class docutils literal notranslate"><span class="pre">DictConfigurator</span></code> 或其超类 <code class="xref py py-class docutils literal notranslate"><span class="pre">BaseConfigurator</span></code> 类的 <code class="xref py py-attr docutils literal notranslate"><span class="pre">importer</span></code> 属性。 但是你必须小心谨慎，因为函数是从类中通过描述器方式来访问的。 如果你使用 Python 可调用对象来执行导入，并且你希望在类层级而不是在实例层级上定义它，则你需要用 <a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> 来装饰它。 例如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">importlib</span> <span class="kn">import</span> <span class="n">import_module</span>
|
||
<span class="kn">from</span> <span class="nn">logging.config</span> <span class="kn">import</span> <span class="n">BaseConfigurator</span>
|
||
|
||
<span class="n">BaseConfigurator</span><span class="o">.</span><span class="n">importer</span> <span class="o">=</span> <span class="nb">staticmethod</span><span class="p">(</span><span class="n">import_module</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果你是在一个配置器的 <em>实例</em> 上设置导入可调用对象则你不需要用 <a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> 来装饰。</p>
|
||
</section>
|
||
</section>
|
||
<section id="configuration-file-format">
|
||
<span id="logging-config-fileformat"></span><h2>配置文件格式<a class="headerlink" href="#configuration-file-format" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> 所能理解的配置文件格式是基于 <a class="reference internal" href="configparser.html#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> 功能的。 该文件必须包含 <code class="docutils literal notranslate"><span class="pre">[loggers]</span></code>, <code class="docutils literal notranslate"><span class="pre">[handlers]</span></code> 和 <code class="docutils literal notranslate"><span class="pre">[formatters]</span></code> 等小节，它们通过名称来标识文件中定义的每种类型的实体。 对于每个这样的实体，都有单独的小节来标识实体的配置方式。 因此，对于 <code class="docutils literal notranslate"><span class="pre">[loggers]</span></code> 小节中名为 <code class="docutils literal notranslate"><span class="pre">log01</span></code> 的日志记录器，相应的配置详情保存在 <code class="docutils literal notranslate"><span class="pre">[logger_log01]</span></code> 小节中。 类似地，对于 <code class="docutils literal notranslate"><span class="pre">[handlers]</span></code> 小节中名为 <code class="docutils literal notranslate"><span class="pre">hand01</span></code> 的处理器，其配置将保存在名为 <code class="docutils literal notranslate"><span class="pre">[handler_hand01]</span></code> 的小节中，而对于 <code class="docutils literal notranslate"><span class="pre">[formatters]</span></code> 小节中名为 <code class="docutils literal notranslate"><span class="pre">form01</span></code> 的格式化器，其配置将在名为 <code class="docutils literal notranslate"><span class="pre">[formatter_form01]</span></code> 的小节中指定。 根日志记录器的配置必须在名为 <code class="docutils literal notranslate"><span class="pre">[logger_root]</span></code> 的小节中指定。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p><a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> API 比 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> API 更旧因而没有提供涵盖日志记录特定方面的功能。 例如，你无法配置 <a class="reference internal" href="logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> 对象，该对象使用 <a class="reference internal" href="#logging.config.fileConfig" title="logging.config.fileConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">fileConfig()</span></code></a> 提供超出简单整数级别的消息过滤功能。 如果你想要在你的日志记录配置中包含 <a class="reference internal" href="logging.html#logging.Filter" title="logging.Filter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Filter</span></code></a> 的实例，你将必须使用 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a>。 请注意未来还将向 <a class="reference internal" href="#logging.config.dictConfig" title="logging.config.dictConfig"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictConfig()</span></code></a> 添加对配置功能的强化，因此值得考虑在方便的时候转换到这个新 API。</p>
|
||
</div>
|
||
<p>在文件中这些小节的例子如下所示。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[loggers]</span>
|
||
<span class="na">keys</span><span class="o">=</span><span class="s">root,log02,log03,log04,log05,log06,log07</span>
|
||
|
||
<span class="k">[handlers]</span>
|
||
<span class="na">keys</span><span class="o">=</span><span class="s">hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09</span>
|
||
|
||
<span class="k">[formatters]</span>
|
||
<span class="na">keys</span><span class="o">=</span><span class="s">form01,form02,form03,form04,form05,form06,form07,form08,form09</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>根日志记录器必须指定一个级别和一个处理器列表。 根日志小节的例子如下所示。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[logger_root]</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">NOTSET</span>
|
||
<span class="na">handlers</span><span class="o">=</span><span class="s">hand01</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">level</span></code> 条目可以为 <code class="docutils literal notranslate"><span class="pre">DEBUG,</span> <span class="pre">INFO,</span> <span class="pre">WARNING,</span> <span class="pre">ERROR,</span> <span class="pre">CRITICAL</span></code> 或 <code class="docutils literal notranslate"><span class="pre">NOTSET</span></code> 之一。 其中 <code class="docutils literal notranslate"><span class="pre">NOTSET</span></code> 仅适用于根日志记录器，表示将会记录所有消息。 级别值会在 <code class="docutils literal notranslate"><span class="pre">logging</span></code> 包命名空间的上下文中通过 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> 来得出。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">handlers</span></code> 条目是以逗号分隔的处理器名称列表，它必须出现于 <code class="docutils literal notranslate"><span class="pre">[handlers]</span></code> 小节并且在配置文件中有相应的小节。</p>
|
||
<p>对于根日志记录器以外的日志记录器，还需要某些附加信息。 下面的例子演示了这些信息。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[logger_parser]</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">DEBUG</span>
|
||
<span class="na">handlers</span><span class="o">=</span><span class="s">hand01</span>
|
||
<span class="na">propagate</span><span class="o">=</span><span class="s">1</span>
|
||
<span class="na">qualname</span><span class="o">=</span><span class="s">compiler.parser</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">level</span></code> 和 <code class="docutils literal notranslate"><span class="pre">handlers</span></code> 条目的解释方式与根日志记录器的一致，不同之处在于如果一个非根日志记录器的级别被指定为 <code class="docutils literal notranslate"><span class="pre">NOTSET</span></code>，则系统会咨询更高层级的日志记录器来确定该日志记录器的有效级别。 <code class="docutils literal notranslate"><span class="pre">propagate</span></code> 条目设为 1 表示消息必须从此日志记录器传播到更高层级的处理器，设为 0 表示消息 <strong>不会</strong> 传播到更高层级的处理器。 <code class="docutils literal notranslate"><span class="pre">qualname</span></code> 条目是日志记录器的层级通道名称，也就是应用程序获取日志记录器所用的名称。</p>
|
||
<p>指定处理器配置的小节说明如下。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[handler_hand01]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">StreamHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">NOTSET</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form01</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">(sys.stdout,)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">class</span></code> 条目指明处理器的类（由 <code class="docutils literal notranslate"><span class="pre">logging</span></code> 包命名空间中的 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> 来确定）。 <code class="docutils literal notranslate"><span class="pre">level</span></code> 会以与日志记录器相同的方式来解读，<code class="docutils literal notranslate"><span class="pre">NOTSET</span></code> 会被视为表示‘记录一切消息’。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">formatter</span></code> 条目指明此处理器的格式化器的键名称。 如为空白，则会使用默认的格式化器 (<code class="docutils literal notranslate"><span class="pre">logging._defaultFormatter</span></code>)。 如果指定了名称，则它必须出现于 <code class="docutils literal notranslate"><span class="pre">[formatters]</span></code> 小节并且在配置文件中有相应的小节。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">args</span></code> 条目，当在 <code class="docutils literal notranslate"><span class="pre">logging</span></code> 包命名空间的上下文中执行 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> 时将是传给处理器类构造器的参数列表。 请参阅相应处理器的构造器说明或者下面的示例，以了解典型的条目是如何构造的。 如果未提供，则默认为 <code class="docutils literal notranslate"><span class="pre">()</span></code>。</p>
|
||
<p>可选的 <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> 条目，当在 <code class="docutils literal notranslate"><span class="pre">logging</span></code> 包命名空间的上下文中执行 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> 时将是传给处理器的构造器的关键字参数字典。 如果未提供，则默认为 <code class="docutils literal notranslate"><span class="pre">{}</span></code>。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[handler_hand02]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">FileHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">DEBUG</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form02</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('python.log', 'w')</span>
|
||
|
||
<span class="k">[handler_hand03]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.SocketHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">INFO</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form03</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)</span>
|
||
|
||
<span class="k">[handler_hand04]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.DatagramHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">WARN</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form04</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)</span>
|
||
|
||
<span class="k">[handler_hand05]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.SysLogHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">ERROR</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form05</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)</span>
|
||
|
||
<span class="k">[handler_hand06]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.NTEventLogHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">CRITICAL</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form06</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('Python Application', '', 'Application')</span>
|
||
|
||
<span class="k">[handler_hand07]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.SMTPHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">WARN</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form07</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')</span>
|
||
<span class="na">kwargs</span><span class="o">=</span><span class="s">{'timeout': 10.0}</span>
|
||
|
||
<span class="k">[handler_hand08]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.MemoryHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">NOTSET</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form08</span>
|
||
<span class="na">target</span><span class="o">=</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">(10, ERROR)</span>
|
||
|
||
<span class="k">[handler_hand09]</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">handlers.HTTPHandler</span>
|
||
<span class="na">level</span><span class="o">=</span><span class="s">NOTSET</span>
|
||
<span class="na">formatter</span><span class="o">=</span><span class="s">form09</span>
|
||
<span class="na">args</span><span class="o">=</span><span class="s">('localhost:9022', '/log', 'GET')</span>
|
||
<span class="na">kwargs</span><span class="o">=</span><span class="s">{'secure': True}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>指定格式化器配置的小节说明如下。</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[formatter_form01]</span>
|
||
<span class="na">format</span><span class="o">=</span><span class="s">F1 %(asctime)s %(levelname)s %(message)s</span>
|
||
<span class="na">datefmt</span><span class="o">=</span>
|
||
<span class="na">class</span><span class="o">=</span><span class="s">logging.Formatter</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">format</span></code> 是整个格式字符串，而 <code class="docutils literal notranslate"><span class="pre">datefmt</span></code> 条目则是兼容 <code class="xref py py-func docutils literal notranslate"><span class="pre">strftime()</span></code> 的日期/时间格式字符串。 如果为空，此包将替换任何接近于日期格式字符串 <code class="docutils literal notranslate"><span class="pre">'%Y-%m-%d</span> <span class="pre">%H:%M:%S'</span></code> 的内容。 此格式还指定了毫秒，并使用逗号分隔符将其附加到结果当中。 此格式的时间示例如 <code class="docutils literal notranslate"><span class="pre">2003-01-23</span> <span class="pre">00:29:50,411</span></code>。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">class</span></code> 条目是可选的。 它指明格式化器类的名称（形式为带点号的模块名加类名。） 此选项适用于实例化 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 的子类。 <a class="reference internal" href="logging.html#logging.Formatter" title="logging.Formatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">Formatter</span></code></a> 的子类可通过扩展或收缩格式来显示异常回溯信息。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>由于如上所述使用了 <a class="reference internal" href="functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a>，因此使用 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 通过套接字来发送和接收配置会导致潜在的安全风险。 此风险仅限于相互间没有信任的多个用户在同一台机器上运行代码的情况；请参阅 <a class="reference internal" href="#logging.config.listen" title="logging.config.listen"><code class="xref py py-func docutils literal notranslate"><span class="pre">listen()</span></code></a> 了解更多信息。</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt>模块 <a class="reference internal" href="logging.html#module-logging" title="logging: Flexible event logging system for applications."><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code></a></dt><dd><p>日志记录模块的 API 参考。</p>
|
||
</dd>
|
||
<dt><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>日志记录模块附带的有用处理器。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.config</span></code> --- 日志记录配置</a><ul>
|
||
<li><a class="reference internal" href="#configuration-functions">配置函数</a></li>
|
||
<li><a class="reference internal" href="#configuration-dictionary-schema">配置字典架构</a><ul>
|
||
<li><a class="reference internal" href="#dictionary-schema-details">字典架构细节</a></li>
|
||
<li><a class="reference internal" href="#incremental-configuration">增量配置</a></li>
|
||
<li><a class="reference internal" href="#object-connections">对象连接</a></li>
|
||
<li><a class="reference internal" href="#user-defined-objects">用户定义对象</a></li>
|
||
<li><a class="reference internal" href="#access-to-external-objects">访问外部对象</a></li>
|
||
<li><a class="reference internal" href="#access-to-internal-objects">访问内部对象</a></li>
|
||
<li><a class="reference internal" href="#import-resolution-and-custom-importers">导入解析与定制导入器</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#configuration-file-format">配置文件格式</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="logging.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging</span></code> --- Python 的日志记录工具</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="logging.handlers.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">logging.handlers</span></code> --- 日志处理程序</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/logging.config.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.handlers.html" title="logging.handlers --- 日志处理程序"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="logging.html" title="logging --- Python 的日志记录工具"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" >通用操作系统服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |