<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Logging — Stem 1.1.0 documentation</title>
<link rel="stylesheet" href="../../_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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/theme_extras.js"></script>
<link rel="shortcut icon" href="../../_static/favicon.png"/>
<link rel="top" title="Stem 1.1.0 documentation" href="../../index.html" />
<link rel="up" title="Contents" href="../../contents.html" />
<link rel="next" title="Proc Utilities" href="proc.html" />
<link rel="prev" title="Enumerations" href="enum.html" />
</head>
<body>
<div class="header"><img class="rightlogo" src="../../_static/logo.png" alt="Logo"/><h1 class="heading"><a href="../../index.html">
<span>Stem Docs</span></a></h1>
<h2 class="heading"><span>Logging</span></h2>
</div>
<div class="topnav">
<p>
<ul id="navbar">
<li><a href="../../index.html">Home</a></li>
<li><a href="../../tutorials.html">Tutorials</a>
<ul>
<li><a href="../../tutorials/the_little_relay_that_could.html">Hello World</a></li>
<li><a href="../../tutorials/to_russia_with_love.html">Client Usage</a></li>
<li><a href="../../tutorials/tortoise_and_the_hare.html">Event Listening</a></li>
<li><a href="../../tutorials/mirror_mirror_on_the_wall.html">Tor Descriptors</a></li>
<li><a href="../../tutorials/east_of_the_sun.html">Utilities</a></li>
<li><a href="../../tutorials/double_double_toil_and_trouble.html">Examples</a></li>
</ul>
</li>
<li><a href="../../api.html">API</a>
<ul>
<li><a href="../control.html">stem.control</a></li>
<li><a href="../connection.html">stem.connection</a></li>
<li><a href="../socket.html">stem.socket</a></li>
<li><a href="../process.html">stem.process</a></li>
<li><a href="../response.html">stem.response</a></li>
<li><a href="../exit_policy.html">stem.exit_policy</a></li>
<li><a href="../version.html">stem.version</a></li>
<li><a href="../../api.html#descriptors">Descriptors</a></li>
<li><a href="../../api.html#utilities">Utilities</a></li>
</ul>
</li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem">Development</a>
<ul>
<li><a href="../../faq.html">FAQ</a></li>
<li><a href="../../change_log.html">Change Log</a></li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs">Bug Tracker</a></li>
<li><a href="../../download.html">Download</a></li>
</ul>
</li>
</ul>
</p>
</div>
<div class="content">
<div class="section" id="module-stem.util.log">
<span id="logging"></span><h1>Logging<a class="headerlink" href="#module-stem.util.log" title="Permalink to this headline">¶</a></h1>
<p>Functions to aid library logging. The default logging
<a class="reference internal" href="#stem.util.log.Runlevel" title="stem.util.log.Runlevel"><tt class="xref py py-data docutils literal"><span class="pre">Runlevel</span></tt></a> is usually NOTICE and above.</p>
<p><strong>Stem users are more than welcome to listen for stem events, but these
functions are not being vended to our users. They may change in the future, use
them at your own risk.</strong></p>
<p><strong>Module Overview:</strong></p>
<div class="highlight-python"><pre>get_logger - provides the stem's Logger instance
logging_level - converts a runlevel to its logging number
escape - escapes special characters in a message in preparation for logging
log - logs a message at the given runlevel
log_once - logs a message, deduplicating if it has already been logged
trace - logs a message at the TRACE runlevel
debug - logs a message at the DEBUG runlevel
info - logs a message at the INFO runlevel
notice - logs a message at the NOTICE runlevel
warn - logs a message at the WARN runlevel
error - logs a message at the ERROR runlevel
LogBuffer - Buffers logged events so they can be iterated over.
|- is_empty - checks if there's events in our buffer
+- __iter__ - iterates over and removes the buffered events
log_to_stdout - reports further logged events to stdout</pre>
</div>
<dl class="data">
<dt id="stem.util.log.Runlevel">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">Runlevel</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.util.log.Runlevel" title="Permalink to this definition">¶</a></dt>
<dd><p>Enumeration for logging runlevels.</p>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="86%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Runlevel</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ERROR</strong></td>
<td>critical issue occurred, the user needs to be notified</td>
</tr>
<tr class="row-odd"><td><strong>WARN</strong></td>
<td>non-critical issue occurred that the user should be aware of</td>
</tr>
<tr class="row-even"><td><strong>NOTICE</strong></td>
<td>information that is helpful to the user</td>
</tr>
<tr class="row-odd"><td><strong>INFO</strong></td>
<td>high level library activity</td>
</tr>
<tr class="row-even"><td><strong>DEBUG</strong></td>
<td>low level library activity</td>
</tr>
<tr class="row-odd"><td><strong>TRACE</strong></td>
<td>request/reply logging</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.get_logger">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">get_logger</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#get_logger"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.get_logger" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the stem logger.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><strong>logging.Logger</strong> for stem</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.logging_level">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">logging_level</tt><big>(</big><em>runlevel</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#logging_level"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.logging_level" title="Permalink to this definition">¶</a></dt>
<dd><p>Translates a runlevel into the value expected by the logging module.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>runlevel</strong> (<a class="reference internal" href="#stem.util.log.Runlevel" title="stem.util.log.Runlevel"><em>stem.util.log.Runlevel</em></a>) – runlevel to be returned, no logging if <strong>None</strong></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.escape">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">escape</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#escape"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.escape" title="Permalink to this definition">¶</a></dt>
<dd><p>Escapes specific sequences for logging (newlines, tabs, carriage returns). If
the input is <strong>bytes</strong> then this converts it to <strong>unicode</strong> under python 3.x.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>message</strong> (<em>str</em>) – string to be escaped</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">str that is escaped</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.log">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">log</tt><big>(</big><em>runlevel</em>, <em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#log"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.log" title="Permalink to this definition">¶</a></dt>
<dd><p>Logs a message at the given runlevel.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>runlevel</strong> (<a class="reference internal" href="#stem.util.log.Runlevel" title="stem.util.log.Runlevel"><em>stem.util.log.Runlevel</em></a>) – runlevel to log the message at, logging is skipped if <strong>None</strong></li>
<li><strong>message</strong> (<em>str</em>) – message to be logged</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.log_once">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">log_once</tt><big>(</big><em>message_id</em>, <em>runlevel</em>, <em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#log_once"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.log_once" title="Permalink to this definition">¶</a></dt>
<dd><p>Logs a message at the given runlevel. If a message with this ID has already
been logged then this is a no-op.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>message_id</strong> (<em>str</em>) – unique message identifier to deduplicate on</li>
<li><strong>runlevel</strong> (<a class="reference internal" href="#stem.util.log.Runlevel" title="stem.util.log.Runlevel"><em>stem.util.log.Runlevel</em></a>) – runlevel to log the message at, logging is skipped if <strong>None</strong></li>
<li><strong>message</strong> (<em>str</em>) – message to be logged</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><strong>True</strong> if we log the message, <strong>False</strong> otherwise</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.trace">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">trace</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#trace"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.trace" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="stem.util.log.debug">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">debug</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#debug"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.debug" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="stem.util.log.info">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">info</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#info"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.info" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="stem.util.log.notice">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">notice</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#notice"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.notice" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="stem.util.log.warn">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">warn</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#warn"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.warn" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="stem.util.log.error">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">error</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#error"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.error" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="stem.util.log.LogBuffer">
<em class="property">class </em><tt class="descclassname">stem.util.log.</tt><tt class="descname">LogBuffer</tt><big>(</big><em>runlevel</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#LogBuffer"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.LogBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">logging.Handler</span></tt></p>
<p>Basic log handler that listens for stem events and stores them so they can be
read later. Log entries are cleared as they are read.</p>
<dl class="method">
<dt id="stem.util.log.LogBuffer.is_empty">
<tt class="descname">is_empty</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#LogBuffer.is_empty"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.LogBuffer.is_empty" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="stem.util.log.LogBuffer.emit">
<tt class="descname">emit</tt><big>(</big><em>record</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#LogBuffer.emit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.LogBuffer.emit" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="function">
<dt id="stem.util.log.log_to_stdout">
<tt class="descclassname">stem.util.log.</tt><tt class="descname">log_to_stdout</tt><big>(</big><em>runlevel</em><big>)</big><a class="reference internal" href="../../_modules/stem/util/log.html#log_to_stdout"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.util.log.log_to_stdout" title="Permalink to this definition">¶</a></dt>
<dd><p>Logs further events to stdout.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>runlevel</strong> (<a class="reference internal" href="#stem.util.log.Runlevel" title="stem.util.log.Runlevel"><em>stem.util.log.Runlevel</em></a>) – minimum runlevel a message needs to be to be logged</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
</div>
<div class="bottomnav">
</div>
<div class="footer">
</div>
</body>
</html>
