[Python-checkins] r42293 - python/trunk/Doc/lib/liblogging.tex
vinay.sajip
python-checkins at python.org
Thu Feb 9 09:54:12 CET 2006
Author: vinay.sajip
Date: Thu Feb 9 09:54:11 2006
New Revision: 42293
Modified:
python/trunk/Doc/lib/liblogging.tex
Log:
Added information on function name added to LogRecord, and the 'extra' keyword parameter.
Modified: python/trunk/Doc/lib/liblogging.tex
==============================================================================
--- python/trunk/Doc/lib/liblogging.tex (original)
+++ python/trunk/Doc/lib/liblogging.tex Thu Feb 9 09:54:11 2006
@@ -183,12 +183,52 @@
\begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{DEBUG} on the root logger.
The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{msg}. The only keyword argument in
-\var{kwargs} which is inspected is \var{exc_info} which, if it does not
-evaluate as false, causes exception information to be added to the logging
-message. If an exception tuple (in the format returned by
-\function{sys.exc_info()}) is provided, it is used; otherwise,
-\function{sys.exc_info()} is called to get the exception information.
+arguments which are merged into \var{msg} using the string formatting
+operator. (Note that this means that you can use keywords in the
+format string, together with a single dictionary argument.)
+
+There are two keyword arguments in \var{kwargs} which are inspected:
+\var{exc_info} which, if it does not evaluate as false, causes exception
+information to be added to the logging message. If an exception tuple (in the
+format returned by \function{sys.exc_info()}) is provided, it is used;
+otherwise, \function{sys.exc_info()} is called to get the exception
+information.
+
+The other optional keyword argument is \var{extra} which can be used to pass
+a dictionary which is used to populate the __dict__ of the LogRecord created
+for the logging event with user-defined attributes. These custom attributes
+can then be used as you like. For example, they could be incorporated into
+logged messages. For example:
+
+\begin{verbatim}
+ FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
+ logging.basicConfig(format=FORMAT)
+ dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
+ logging.warning("Protocol problem: %s", "connection reset", extra=d)
+\end{verbatim}
+
+would print something like
+\begin{verbatim}
+2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
+\end{verbatim}
+
+The keys in the dictionary passed in \var{extra} should not clash with the keys
+used by the logging system. (See the \class{Formatter} documentation for more
+information on which keys are used by the logging system.)
+
+If you choose to use these attributes in logged messages, you need to exercise
+some care. In the above example, for instance, the \class{Formatter} has been
+set up with a format string which expects 'clientip' and 'user' in the
+attribute dictionary of the LogRecord. If these are missing, the message will
+not be logged because a string formatting exception will occur. So in this
+case, you always need to pass the \var{extra} dictionary with these keys.
+
+While this might be annoying, this feature is intended for use in specialized
+circumstances, such as multi-threaded servers where the same code executes
+in many contexts, and interesting conditions which arise are dependent on this
+context (such as remote client IP address and authenticated user name, in the
+above example). In such circumstances, it is likely that specialized
+\class{Formatter}s would be used with particular \class{Handler}s.
\end{funcdesc}
\begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
@@ -367,12 +407,53 @@
\begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{DEBUG} on this logger.
The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{msg}. The only keyword argument in
-\var{kwargs} which is inspected is \var{exc_info} which, if it does not
-evaluate as false, causes exception information to be added to the logging
-message. If an exception tuple (as provided by \function{sys.exc_info()})
-is provided, it is used; otherwise, \function{sys.exc_info()} is called
-to get the exception information.
+arguments which are merged into \var{msg} using the string formatting
+operator. (Note that this means that you can use keywords in the
+format string, together with a single dictionary argument.)
+
+There are two keyword arguments in \var{kwargs} which are inspected:
+\var{exc_info} which, if it does not evaluate as false, causes exception
+information to be added to the logging message. If an exception tuple (in the
+format returned by \function{sys.exc_info()}) is provided, it is used;
+otherwise, \function{sys.exc_info()} is called to get the exception
+information.
+
+The other optional keyword argument is \var{extra} which can be used to pass
+a dictionary which is used to populate the __dict__ of the LogRecord created
+for the logging event with user-defined attributes. These custom attributes
+can then be used as you like. For example, they could be incorporated into
+logged messages. For example:
+
+\begin{verbatim}
+ FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
+ logging.basicConfig(format=FORMAT)
+ dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
+ logger = logging.getLogger("tcpserver")
+ logger.warning("Protocol problem: %s", "connection reset", extra=d)
+\end{verbatim}
+
+would print something like
+\begin{verbatim}
+2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
+\end{verbatim}
+
+The keys in the dictionary passed in \var{extra} should not clash with the keys
+used by the logging system. (See the \class{Formatter} documentation for more
+information on which keys are used by the logging system.)
+
+If you choose to use these attributes in logged messages, you need to exercise
+some care. In the above example, for instance, the \class{Formatter} has been
+set up with a format string which expects 'clientip' and 'user' in the
+attribute dictionary of the LogRecord. If these are missing, the message will
+not be logged because a string formatting exception will occur. So in this
+case, you always need to pass the \var{extra} dictionary with these keys.
+
+While this might be annoying, this feature is intended for use in specialized
+circumstances, such as multi-threaded servers where the same code executes
+in many contexts, and interesting conditions which arise are dependent on this
+context (such as remote client IP address and authenticated user name, in the
+above example). In such circumstances, it is likely that specialized
+\class{Formatter}s would be used with particular \class{Handler}s.
\end{methoddesc}
\begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
@@ -441,7 +522,8 @@
\method{filter()}.
\end{methoddesc}
-\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
+\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info,
+ func, extra}
This is a factory method which can be overridden in subclasses to create
specialized \class{LogRecord} instances.
\end{methoddesc}
@@ -1305,6 +1387,7 @@
call was issued (if available).}
\lineii{\%(filename)s} {Filename portion of pathname.}
\lineii{\%(module)s} {Module (name portion of filename).}
+\lineii{\%(funcName)s} {Name of function containing the logging call.}
\lineii{\%(lineno)d} {Source line number where the logging call was issued
(if available).}
\lineii{\%(created)f} {Time when the \class{LogRecord} was created (as
More information about the Python-checkins
mailing list