Merged revisions 59822-59841 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59822 | georg.brandl | 2008-01-07 17:43:47 +0100 (Mon, 07 Jan 2008) | 2 lines
Restore "somenamedtuple" as the "class" for named tuple attrs.
........
r59824 | georg.brandl | 2008-01-07 18:09:35 +0100 (Mon, 07 Jan 2008) | 2 lines
Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode.
........
r59827 | georg.brandl | 2008-01-07 18:25:53 +0100 (Mon, 07 Jan 2008) | 2 lines
patch #1668: clarify envvar docs; rename THREADDEBUG to PYTHONTHREADDEBUG.
........
r59830 | georg.brandl | 2008-01-07 19:16:36 +0100 (Mon, 07 Jan 2008) | 2 lines
Make Python compile with --disable-unicode.
........
r59831 | georg.brandl | 2008-01-07 19:23:27 +0100 (Mon, 07 Jan 2008) | 2 lines
Restructure urllib doc structure.
........
r59833 | georg.brandl | 2008-01-07 19:41:34 +0100 (Mon, 07 Jan 2008) | 2 lines
Fix #define ordering.
........
r59834 | georg.brandl | 2008-01-07 19:47:44 +0100 (Mon, 07 Jan 2008) | 2 lines
#467924, patch by Alan McIntyre: Add ZipFile.extract and ZipFile.extractall.
........
r59835 | raymond.hettinger | 2008-01-07 19:52:19 +0100 (Mon, 07 Jan 2008) | 1 line
Fix inconsistent title levels -- it made the whole doc build crash horribly.
........
r59836 | georg.brandl | 2008-01-07 19:57:03 +0100 (Mon, 07 Jan 2008) | 2 lines
Fix two further doc build warnings.
........
r59837 | georg.brandl | 2008-01-07 20:17:10 +0100 (Mon, 07 Jan 2008) | 2 lines
Clarify metaclass docs and add example.
........
r59838 | vinay.sajip | 2008-01-07 20:40:10 +0100 (Mon, 07 Jan 2008) | 1 line
Added section about adding contextual information to log output.
........
r59839 | christian.heimes | 2008-01-07 20:58:41 +0100 (Mon, 07 Jan 2008) | 1 line
Fixed indention problem that caused the second TIPC test to run on systems without TIPC
........
r59840 | raymond.hettinger | 2008-01-07 21:07:38 +0100 (Mon, 07 Jan 2008) | 1 line
Cleanup named tuple subclassing example.
........
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index bf6ad71..af8c867 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1118,6 +1118,52 @@
combination of handlers you choose.
+.. _context-info:
+
+Adding contextual information to your logging output
+----------------------------------------------------
+
+Sometimes you want logging output to contain contextual information in
+addition to the parameters passed to the logging call. For example, in a
+networked application, it may be desirable to log client-specific information
+in the log (e.g. remote client's username, or IP address). Although you could
+use the *extra* parameter to achieve this, it's not always convenient to pass
+the information in this way. While it might be tempting to create
+:class:`Logger` instances on a per-connection basis, this is not a good idea
+because these instances are not garbage collected. While this is not a problem
+in practice, when the number of :class:`Logger` instances is dependent on the
+level of granularity you want to use in logging an application, it could
+be hard to manage if the number of :class:`Logger` instances becomes
+effectively unbounded.
+
+There are a number of other ways you can pass contextual information to be
+output along with logging event information.
+
+* Use an adapter class which has access to the contextual information and
+ which defines methods :meth:`debug`, :meth:`info` etc. with the same
+ signatures as used by :class:`Logger`. You instantiate the adapter with a
+ name, which will be used to create an underlying :class:`Logger` with that
+ name. In each adpater method, the passed-in message is modified to include
+ whatever contextual information you want.
+
+* Use something other than a string to pass the message. Although normally
+ the first argument to a logger method such as :meth:`debug`, :meth:`info`
+ etc. is usually a string, it can in fact be any object. This object is the
+ argument to a :func:`str()` call which is made, in
+ :meth:`LogRecord.getMessage`, to obtain the actual message string. You can
+ use this behavior to pass an instance which may be initialized with a
+ logging message, which redefines :meth:__str__ to return a modified version
+ of that message with the contextual information added.
+
+* Use a specialized :class:`Formatter` subclass to add additional information
+ to the formatted output. The subclass could, for instance, merge some thread
+ local contextual information (or contextual information obtained in some
+ other way) with the output generated by the base :class:`Formatter`.
+
+In each of these three approaches, thread locals can sometimes be a useful way
+of passing contextual information without undue coupling between different
+parts of your code.
+
.. _network-logging:
Sending and receiving logging events across a network