Added information on function name added to LogRecord, and the 'extra' keyword parameter.

1 files changed, 96 insertions, 13 deletions

diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex
index cf1658d..63293d6 100644
--- a/Doc/lib/liblogging.tex
+++ b/Doc/lib/liblogging.tex
@@ -183,12 +183,52 @@ will not undo customisations already applied by other code. For example:
 \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 @@ other than \constant{NOTSET} is found, and that value is returned.
 \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 @@ as those created locally. Logger-level filtering is applied using
 \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 @@ Currently, the useful mapping keys in a \class{LogRecord} are:
                         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