Sophie: python-twisted-core-doc-2.5.0-3mdv2008.1 x86

python-twisted-core-doc-2.5.0-3mdv2008.1.x86_64.rpm

<?xml version="1.0"?><!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" lang="en"><head><title>Twisted Documentation: Logging with twisted.python.log</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Logging with twisted.python.log</h1><div class="toc"><ol><li><a href="#auto0">Basic usage</a></li><ul><li><a href="#auto1">Logging and twistd</a></li><li><a href="#auto2">Log files</a></li></ul><li><a href="#auto3">Writing log observers</a></li></ol></div><div class="content"><span></span><h2>Basic usage<a name="auto0"></a></h2><p>Twisted provides a simple and flexible logging system in the <code class="API">twisted.python.log</code> module.  It has three commonly used
    functions:</p><dl><dt><code base="twisted.python.log" class="API">msg</code></dt><dd>Logs a new message.  For example:
        <pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">log</span>
<span class="py-src-variable">log</span>.<span class="py-src-variable">msg</span>(<span class="py-src-string">'Hello, world.'</span>)
</pre></dd><dt><code base="twisted.python.log" class="API">err</code></dt><dd>Writes a failure to the log, including traceback information (if any).
      You can pass it a <code base="twisted.python.failure" class="API">Failure</code> or Exception instance, or
      nothing.  If you pass something else, it will be converted to a string
      with <code>repr</code> and logged.
      
      If you pass nothing, it will construct a Failure from the
      currently active exception, which makes it convenient to use in an <code class="python">except</code> clause:
        <pre class="python">
<span class="py-src-keyword">try</span>:
    <span class="py-src-variable">x</span> = <span class="py-src-number">1</span> / <span class="py-src-number">0</span>
<span class="py-src-keyword">except</span>:
    <span class="py-src-variable">log</span>.<span class="py-src-variable">err</span>()   <span class="py-src-comment"># will log the ZeroDivisionError</span>
</pre></dd><dt><code base="twisted.python.log" class="API">startLogging</code></dt><dd>Starts logging to a given file-like object.  For example:
        <pre class="python">
<span class="py-src-variable">log</span>.<span class="py-src-variable">startLogging</span>(<span class="py-src-variable">open</span>(<span class="py-src-string">'/var/log/foo.log'</span>, <span class="py-src-string">'w'</span>))
</pre>
      or:
        <pre class="python">
<span class="py-src-variable">log</span>.<span class="py-src-variable">startLogging</span>(<span class="py-src-variable">sys</span>.<span class="py-src-variable">stdout</span>)
</pre>

      By default, <code>startLogging</code> will also redirect anything written
      to <code>sys.stdout</code> and <code>sys.stderr</code> to the log.  You
      can disable this by passing <code class="python">setStdout=False</code> to
      <code>startLogging</code>.
      </dd></dl><p>Before <code>startLogging</code> is called, log messages will be
    discarded and errors will be written to stderr.</p><h3>Logging and twistd<a name="auto1"></a></h3><p>If you are using <code class="shell">twistd</code> to run your daemon, it
    will take care of calling <code>startLogging</code> for you, and will also
    rotate log files.  See <a href="application.html#twistd">twistd and tac</a>
    and the <code class="shell">twistd</code> man page for details of using
    twistd.</p><h3>Log files<a name="auto2"></a></h3><p>The <code class="API">twisted.python.logfile</code> module provides
    some standard classes suitable for use with <code>startLogging</code>, such
    as <code base="twisted.python.logfile" class="API">DailyLogFile</code>,
    which will rotate the log to a new file once per day.</p><h2>Writing log observers<a name="auto3"></a></h2><p>Log observers are the basis of the Twisted logging system.  An example of
    a log observer in Twisted is the <code base="twisted.python.log" class="API">FileLogObserver</code> used by
    <code>startLogging</code> that writes events to a log file.  A log observer
    is just a callable that accepts a dictionary as its only argument.  You can
    then register it to receive all log events (in addition to any other
    observers):</p><pre class="python">
<span class="py-src-variable">twisted</span>.<span class="py-src-variable">python</span>.<span class="py-src-variable">log</span>.<span class="py-src-variable">addObserver</span>(<span class="py-src-variable">yourCallable</span>)
</pre><p>The dictionary will have at least two items:</p><dl><dt>message</dt><dd>The message (a list, usually of strings)
      for this log event, as passed to <code>log.msg</code> or the
      message in the failure passed to <code>log.err</code>.</dd><dt>isError</dt><dd>This is a boolean that will be true if this event came from a call to
      <code>log.err</code>.  If this is set, there may be a <code>failure</code>
      item in the dictionary as will, with a Failure object in it.</dd></dl><p>Other items the built in logging functionality may add include:</p><dl><dt>printed</dt><dd>This message was captured from <code>sys.stdout</code>, i.e. this
      message came from a <code>print</code> statement.  If
      <code>isError</code> is also true, it came from
      <code>sys.stderr</code>.</dd></dl><p>You can pass additional items to the event dictionary by passing keyword
    arguments to <code>log.msg</code> and <code>log.err</code>.  The standard
    log observers will ignore dictionary items they don't use.</p><p>Important notes:</p><ul><li>Never raise an exception from a log observer.  If your log observer
      raises an exception, it will be removed.</li><li>Never block in a log observer, as it may run in main Twisted thread.
      This means you can't use socket or syslog Python-logging backends.</li><li>The observer needs to be thread safe if you anticipate using threads
      in your program.</li></ul></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 2.5.0</span></body></html>