~justin-fathomdb/nova/justinsb-openstack-api-volumes

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Logging with twisted.python.log</title>

</head>

<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><li><a href="#auto3">Using the Python logging module</a></li></ul><li><a href="#auto4">Writing log observers</a></li><li><a href="#auto5">Customizing twistd logging</a></li></ol></div>

<h2>Basic usage<a name="auto0"/></h2>

Twisted provides a simple and flexible logging system in the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.html" title="twisted.python.log">twisted.python.log</a></code> module. It has three commonly used

functions:

<dl>

<dd>Logs a new message. For example:

<pre class="python">1

from twisted.python import log

log.msg('Hello, world.')

</pre>

</dd>

<dd>Writes a failure to the log, including traceback information (if any).

You can pass it a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">Failure</a></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">1

try:

x = 1 / 0

except:

log.err() # will log the ZeroDivisionError

</pre>

</dd>

<dt><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.startLogging.html" title="twisted.python.log.startLogging">startLogging</a></code></dt>

<dd>Starts logging to a given file-like object. For example:

<pre class="python">1

log.startLogging(open('/var/log/foo.log', 'w'))

</pre>

or:

<pre class="python">1

log.startLogging(sys.stdout)

</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>

Before <code>startLogging</code> is called, log messages will be

discarded and errors will be written to stderr.

<h3>Logging and twistd<a name="auto1"/></h3>

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" shape="rect">twistd and tac</a>

and the <code class="shell">twistd</code> man page for details of using

twistd.

<h3>Log files<a name="auto2"/></h3>

The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.logfile.html" title="twisted.python.logfile">twisted.python.logfile</a></code> module provides

some standard classes suitable for use with <code>startLogging</code>, such

as <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.logfile.DailyLogFile.html" title="twisted.python.logfile.DailyLogFile">DailyLogFile</a></code>,

which will rotate the log to a new file once per day.

<h3>Using the Python logging module<a name="auto3"/></h3>

If your application uses the logging module or you want to use its ease

of configuration but don't want to lose twisted-produced messages,

the observer

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.PythonLoggingObserver.html" title="twisted.python.log.PythonLoggingObserver">PythonLoggingObserver</a></code>

should be useful to you

You just start it like any other observers:

<pre class="python">1

observer = log.PythonLoggingObserver()

observer.start()

</pre>

And then you'll just have to configure logging to do what you want:

logging documentation</a>.

100

101

This method allows you to customize the log level received by the

102

logging module using the <code>logLevel</code> keyword:

103

<pre class="python">1

104

105

log.msg("This is important!", logLevel=logging.CRITICAL)

106

log.msg("Don't mind", logLevel=logging.DEBUG)

107

</pre>

108

Unless logLevel is provided, logging.INFO is used for <code>log.msg</code>

109

and logging.ERROR is used for <code>log.err</code>.

110

111

112

One special care should be made when you use special configuration of

113

the python logging module: some handlers (e.g. SMTP, HTTP) uses network

114

so can block inside the reactor loop. Nothing in the bridge is

115

done to prevent that.

116

117

<h2>Writing log observers<a name="auto4"/></h2>

118

119

Log observers are the basis of the Twisted logging system. An example of

120

a log observer in Twisted is the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.FileLogObserver.html" title="twisted.python.log.FileLogObserver">FileLogObserver</a></code> used by

121

<code>startLogging</code> that writes events to a log file. A log observer

122

is just a callable that accepts a dictionary as its only argument. You can

123

then register it to receive all log events (in addition to any other

124

observers):

125

126

<pre class="python">1

127

twisted.python.log.addObserver(yourCallable)

128

</pre>

129

130

The dictionary will have at least two items:

131

132

<dl>

133

<dt>message</dt>

134

<dd>The message (a list, usually of strings)

135

for this log event, as passed to <code>log.msg</code> or the

136

message in the failure passed to <code>log.err</code>.</dd>

137

138

<dt>isError</dt>

139

<dd>This is a boolean that will be true if this event came from a call to

140

<code>log.err</code>. If this is set, there may be a <code>failure</code>

141

item in the dictionary as will, with a Failure object in it.</dd>

142

</dl>

143

144

Other items the built in logging functionality may add include:

145

146

<dl>

147

<dt>printed</dt>

148

<dd>This message was captured from <code>sys.stdout</code>, i.e. this

149

message came from a <code>print</code> statement. If

150

<code>isError</code> is also true, it came from

151

<code>sys.stderr</code>.</dd>

152

</dl>

153

154

You can pass additional items to the event dictionary by passing keyword

155

arguments to <code>log.msg</code> and <code>log.err</code>. The standard

156

log observers will ignore dictionary items they don't use.

157

158

Important notes:

159

160

<ul>

161

<li>Never block in a log observer, as it may run in main Twisted thread.

162

This means you can't use socket or syslog Python-logging backends.</li>

163

164

<li>The observer needs to be thread safe if you anticipate using threads

165

in your program.</li>

166

</ul>

167

168

<h2>Customizing <code>twistd</code> logging<a name="auto5"/></h2>

169

170

The behavior of the logging that <code>twistd</code> does can be customized

171

by setting the <code>ILogObserver</code> component on the application

172

object. See the <a href="application.html" shape="rect">Application document</a> for

173

more information.

174

175

176

</div>

177

178

<a href="index.html">Index</a>

179

Version: 10.0.0

180

</body>

181

</html>

b'\\ No newline at end of file'

Older »