mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-12-14 04:17:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Vinay Sajip 2006-02-09 08:54:11 +00:00
parent ed1992f2aa
commit b4549c4a7e
1 changed files with 96 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
Doc/lib/liblogging.tex
View File

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