n | |
| :mod:`logging` --- Logging facility for Python |
| ============================================== |
| |
| .. module:: logging |
n | :synopsis: Flexible error logging system for applications. |
| |
| |
| .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com> |
| .. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com> |
| |
| |
n | .. % These apply to all modules, and may be given more than once: |
| |
| |
| |
| .. index:: pair: Errors; logging |
| |
| .. versionadded:: 2.3 |
| |
| This module defines functions and classes which implement a flexible error |
| logging system for applications. |
| |
| Logging is performed by calling methods on instances of the :class:`Logger` |
| class (hereafter called :dfn:`loggers`). Each instance has a name, and they are |
n | conceptually arranged in a name space hierarchy using dots (periods) as |
n | conceptually arranged in a namespace hierarchy using dots (periods) as |
| separators. For example, a logger named "scan" is the parent of loggers |
| "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, |
| and indicate the area of an application in which a logged message originates. |
| |
| Logged messages also have levels of importance associated with them. The default |
| levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, |
| :const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the |
| importance of a logged message by calling an appropriate method of |
| :class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`, |
| :meth:`error` and :meth:`critical`, which mirror the default levels. You are not |
| constrained to use these levels: you can specify your own and use a more general |
| :class:`Logger` method, :meth:`log`, which takes an explicit level argument. |
n | |
| |
| Logging tutorial |
| ---------------- |
| |
| The key benefit of having the logging API provided by a standard library module |
| is that all Python modules can participate in logging, so your application log |
| can include messages from third-party modules. |
| |
| It is, of course, possible to log messages with different verbosity levels or to |
| different destinations. Support for writing log messages to files, HTTP |
| GET/POST locations, email via SMTP, generic sockets, or OS-specific logging |
| mechanisms are all supported by the standard module. You can also create your |
| own log destination class if you have special requirements not met by any of the |
| built-in classes. |
| |
| Simple examples |
| ^^^^^^^^^^^^^^^ |
| |
| .. sectionauthor:: Doug Hellmann |
| .. (see <http://blog.doughellmann.com/2007/05/pymotw-logging.html>) |
| |
| Most applications are probably going to want to log to a file, so let's start |
| with that case. Using the :func:`basicConfig` function, we can set up the |
| default handler so that debug messages are written to a file:: |
| |
| import logging |
| LOG_FILENAME = '/tmp/logging_example.out' |
| logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,) |
| |
| logging.debug('This message should go to the log file') |
| |
| And now if we open the file and look at what we have, we should find the log |
| message:: |
| |
| DEBUG:root:This message should go to the log file |
| |
| If you run the script repeatedly, the additional log messages are appended to |
| the file. To create a new file each time, you can pass a filemode argument to |
| :func:`basicConfig` with a value of ``'w'``. Rather than managing the file size |
| yourself, though, it is simpler to use a :class:`RotatingFileHandler`:: |
| |
| import glob |
| import logging |
| import logging.handlers |
| |
| LOG_FILENAME = '/tmp/logging_rotatingfile_example.out' |
| |
| # Set up a specific logger with our desired output level |
| my_logger = logging.getLogger('MyLogger') |
| my_logger.setLevel(logging.DEBUG) |
| |
| # Add the log message handler to the logger |
| handler = logging.handlers.RotatingFileHandler( |
| LOG_FILENAME, maxBytes=20, backupCount=5) |
| |
| my_logger.addHandler(handler) |
| |
| # Log some messages |
| for i in range(20): |
| my_logger.debug('i = %d' % i) |
| |
| # See what files are created |
| logfiles = glob.glob('%s*' % LOG_FILENAME) |
| |
| for filename in logfiles: |
| print filename |
| |
| The result should be 6 separate files, each with part of the log history for the |
| application:: |
| |
| /tmp/logging_rotatingfile_example.out |
| /tmp/logging_rotatingfile_example.out.1 |
| /tmp/logging_rotatingfile_example.out.2 |
| /tmp/logging_rotatingfile_example.out.3 |
| /tmp/logging_rotatingfile_example.out.4 |
| /tmp/logging_rotatingfile_example.out.5 |
| |
| The most current file is always :file:`/tmp/logging_rotatingfile_example.out`, |
| and each time it reaches the size limit it is renamed with the suffix |
| ``.1``. Each of the existing backup files is renamed to increment the suffix |
| (``.1`` becomes ``.2``, etc.) and the ``.5`` file is erased. |
| |
| Obviously this example sets the log length much much too small as an extreme |
| example. You would want to set *maxBytes* to an appropriate value. |
| |
| Another useful feature of the logging API is the ability to produce different |
| messages at different log levels. This allows you to instrument your code with |
| debug messages, for example, but turning the log level down so that those debug |
| messages are not written for your production system. The default levels are |
| ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG`` and ``NOTSET``. |
| |
| The logger, handler, and log message call each specify a level. The log message |
| is only emitted if the handler and logger are configured to emit messages of |
| that level or lower. For example, if a message is ``CRITICAL``, and the logger |
| is set to ``ERROR``, the message is emitted. If a message is a ``WARNING``, and |
| the logger is set to produce only ``ERROR``\s, the message is not emitted:: |
| |
| import logging |
| import sys |
| |
| LEVELS = {'debug': logging.DEBUG, |
| 'info': logging.INFO, |
| 'warning': logging.WARNING, |
| 'error': logging.ERROR, |
| 'critical': logging.CRITICAL} |
| |
| if len(sys.argv) > 1: |
| level_name = sys.argv[1] |
| level = LEVELS.get(level_name, logging.NOTSET) |
| logging.basicConfig(level=level) |
| |
| logging.debug('This is a debug message') |
| logging.info('This is an info message') |
| logging.warning('This is a warning message') |
| logging.error('This is an error message') |
| logging.critical('This is a critical error message') |
| |
| Run the script with an argument like 'debug' or 'warning' to see which messages |
| show up at different levels:: |
| |
| $ python logging_level_example.py debug |
| DEBUG:root:This is a debug message |
| INFO:root:This is an info message |
| WARNING:root:This is a warning message |
| ERROR:root:This is an error message |
| CRITICAL:root:This is a critical error message |
| |
| $ python logging_level_example.py info |
| INFO:root:This is an info message |
| WARNING:root:This is a warning message |
| ERROR:root:This is an error message |
| CRITICAL:root:This is a critical error message |
| |
| You will notice that these log messages all have ``root`` embedded in them. The |
| logging module supports a hierarchy of loggers with different names. An easy |
| way to tell where a specific log message comes from is to use a separate logger |
| object for each of your modules. Each new logger "inherits" the configuration |
| of its parent, and log messages sent to a logger include the name of that |
| logger. Optionally, each logger can be configured differently, so that messages |
| from different modules are handled in different ways. Let's look at a simple |
| example of how to log from different modules so it is easy to trace the source |
| of the message:: |
| |
| import logging |
| |
| logging.basicConfig(level=logging.WARNING) |
| |
| logger1 = logging.getLogger('package1.module1') |
| logger2 = logging.getLogger('package2.module2') |
| |
| logger1.warning('This message comes from one module') |
| logger2.warning('And this message comes from another module') |
| |
| And the output:: |
| |
| $ python logging_modules_example.py |
| WARNING:package1.module1:This message comes from one module |
| WARNING:package2.module2:And this message comes from another module |
| |
| There are many more options for configuring logging, including different log |
| message formatting options, having messages delivered to multiple destinations, |
| and changing the configuration of a long-running application on the fly using a |
| socket interface. All of these options are covered in depth in the library |
| module documentation. |
| |
| Loggers |
| ^^^^^^^ |
| |
| The logging library takes a modular approach and offers the several categories |
| of components: loggers, handlers, filters, and formatters. Loggers expose the |
| interface that application code directly uses. Handlers send the log records to |
| the appropriate destination. Filters provide a finer grained facility for |
| determining which log records to send on to a handler. Formatters specify the |
| layout of the resultant log record. |
| |
| :class:`Logger` objects have a threefold job. First, they expose several |
| methods to application code so that applications can log messages at runtime. |
| Second, logger objects determine which log messages to act upon based upon |
| severity (the default filtering facility) or filter objects. Third, logger |
| objects pass along relevant log messages to all interested log handlers. |
| |
| The most widely used methods on logger objects fall into two categories: |
| configuration and message sending. |
| |
| * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger |
| will handle, where debug is the lowest built-in severity level and critical is |
| the highest built-in severity. For example, if the severity level is info, |
| the logger will handle only info, warning, error, and critical messages and |
| will ignore debug messages. |
| |
| * :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter |
| objects from the logger object. This tutorial does not address filters. |
| |
| With the logger object configured, the following methods create log messages: |
| |
| * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, |
| :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with |
| a message and a level that corresponds to their respective method names. The |
| message is actually a format string, which may contain the standard string |
| substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The |
| rest of their arguments is a list of objects that correspond with the |
| substitution fields in the message. With regard to :const:`**kwargs`, the |
| logging methods care only about a keyword of :const:`exc_info` and use it to |
| determine whether to log exception information. |
| |
| * :meth:`Logger.exception` creates a log message similar to |
| :meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a |
| stack trace along with it. Call this method only from an exception handler. |
| |
| * :meth:`Logger.log` takes a log level as an explicit argument. This is a |
| little more verbose for logging messages than using the log level convenience |
| methods listed above, but this is how to log at custom log levels. |
| |
| :func:`getLogger` returns a reference to a logger instance with the specified |
| if it it is provided, or ``root`` if not. The names are period-separated |
| hierarchical structures. Multiple calls to :func:`getLogger` with the same name |
| will return a reference to the same logger object. Loggers that are further |
| down in the hierarchical list are children of loggers higher up in the list. |
| For example, given a logger with a name of ``foo``, loggers with names of |
| ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``. |
| Child loggers propagate messages up to their parent loggers. Because of this, |
| it is unnecessary to define and configure all the loggers an application uses. |
| It is sufficient to configure a top-level logger and create child loggers as |
| needed. |
| |
| |
| Handlers |
| ^^^^^^^^ |
| |
| :class:`Handler` objects are responsible for dispatching the appropriate log |
| messages (based on the log messages' severity) to the handler's specified |
| destination. Logger objects can add zero or more handler objects to themselves |
| with an :func:`addHandler` method. As an example scenario, an application may |
| want to send all log messages to a log file, all log messages of error or higher |
| to stdout, and all messages of critical to an email address. This scenario |
| requires three individual handlers where each handler is responsible for sending |
| messages of a specific severity to a specific location. |
| |
| The standard library includes quite a few handler types; this tutorial uses only |
| :class:`StreamHandler` and :class:`FileHandler` in its examples. |
| |
| There are very few methods in a handler for application developers to concern |
| themselves with. The only handler methods that seem relevant for application |
| developers who are using the built-in handler objects (that is, not creating |
| custom handlers) are the following configuration methods: |
| |
| * The :meth:`Handler.setLevel` method, just as in logger objects, specifies the |
| lowest severity that will be dispatched to the appropriate destination. Why |
| are there two :func:`setLevel` methods? The level set in the logger |
| determines which severity of messages it will pass to its handlers. The level |
| set in each handler determines which messages that handler will send on. |
| :func:`setFormatter` selects a Formatter object for this handler to use. |
| |
| * :func:`addFilter` and :func:`removeFilter` respectively configure and |
| deconfigure filter objects on handlers. |
| |
| Application code should not directly instantiate and use handlers. Instead, the |
| :class:`Handler` class is a base class that defines the interface that all |
| Handlers should have and establishes some default behavior that child classes |
| can use (or override). |
| |
| |
| Formatters |
| ^^^^^^^^^^ |
| |
| Formatter objects configure the final order, structure, and contents of the log |
| message. Unlike the base :class:`logging.Handler` class, application code may |
| instantiate formatter classes, although you could likely subclass the formatter |
| if your application needs special behavior. The constructor takes two optional |
| arguments: a message format string and a date format string. If there is no |
| message format string, the default is to use the raw message. If there is no |
| date format string, the default date format is:: |
| |
| %Y-%m-%d %H:%M:%S |
| |
| with the milliseconds tacked on at the end. |
| |
| The message format string uses ``%(<dictionary key>)s`` styled string |
| substitution; the possible keys are documented in :ref:`formatter-objects`. |
| |
| The following message format string will log the time in a human-readable |
| format, the severity of the message, and the contents of the message, in that |
| order:: |
| |
| "%(asctime)s - %(levelname)s - %(message)s" |
| |
| |
| Configuring Logging |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| Programmers can configure logging either by creating loggers, handlers, and |
| formatters explicitly in a main module with the configuration methods listed |
| above (using Python code), or by creating a logging config file. The following |
| code is an example of configuring a very simple logger, a console handler, and a |
| simple formatter in a Python module:: |
| |
| import logging |
| |
| # create logger |
| logger = logging.getLogger("simple_example") |
| logger.setLevel(logging.DEBUG) |
| # create console handler and set level to debug |
| ch = logging.StreamHandler() |
| ch.setLevel(logging.DEBUG) |
| # create formatter |
| formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s") |
| # add formatter to ch |
| ch.setFormatter(formatter) |
| # add ch to logger |
| logger.addHandler(ch) |
| |
| # "application" code |
| logger.debug("debug message") |
| logger.info("info message") |
| logger.warn("warn message") |
| logger.error("error message") |
| logger.critical("critical message") |
| |
| Running this module from the command line produces the following output:: |
| |
| $ python simple_logging_module.py |
| 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message |
| 2005-03-19 15:10:26,620 - simple_example - INFO - info message |
| 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message |
| 2005-03-19 15:10:26,697 - simple_example - ERROR - error message |
| 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message |
| |
| The following Python module creates a logger, handler, and formatter nearly |
| identical to those in the example listed above, with the only difference being |
| the names of the objects:: |
| |
| import logging |
| import logging.config |
| |
| logging.config.fileConfig("logging.conf") |
| |
| # create logger |
| logger = logging.getLogger("simpleExample") |
| |
| # "application" code |
| logger.debug("debug message") |
| logger.info("info message") |
| logger.warn("warn message") |
| logger.error("error message") |
| logger.critical("critical message") |
| |
| Here is the logging.conf file:: |
| |
| [loggers] |
| keys=root,simpleExample |
| |
| [handlers] |
| keys=consoleHandler |
| |
| [formatters] |
| keys=simpleFormatter |
| |
| [logger_root] |
| level=DEBUG |
| handlers=consoleHandler |
| |
| [logger_simpleExample] |
| level=DEBUG |
| handlers=consoleHandler |
| qualname=simpleExample |
| propagate=0 |
| |
| [handler_consoleHandler] |
| class=StreamHandler |
| level=DEBUG |
| formatter=simpleFormatter |
| args=(sys.stdout,) |
| |
| [formatter_simpleFormatter] |
| format=%(asctime)s - %(name)s - %(levelname)s - %(message)s |
| datefmt= |
| |
| The output is nearly identical to that of the non-config-file-based example:: |
| |
| $ python simple_logging_config.py |
| 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message |
| 2005-03-19 15:38:55,979 - simpleExample - INFO - info message |
| 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message |
| 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message |
| 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message |
| |
| You can see that the config file approach has a few advantages over the Python |
| code approach, mainly separation of configuration and code and the ability of |
| noncoders to easily modify the logging properties. |
| |
| .. _library-config: |
| |
| Configuring Logging for a Library |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| When developing a library which uses logging, some consideration needs to be |
| given to its configuration. If the using application does not use logging, and |
| library code makes logging calls, then a one-off message "No handlers could be |
| found for logger X.Y.Z" is printed to the console. This message is intended |
| to catch mistakes in logging configuration, but will confuse an application |
| developer who is not aware of logging by the library. |
| |
| In addition to documenting how a library uses logging, a good way to configure |
| library logging so that it does not cause a spurious message is to add a |
| handler which does nothing. This avoids the message being printed, since a |
| handler will be found: it just doesn't produce any output. If the library user |
| configures logging for application use, presumably that configuration will add |
| some handlers, and if levels are suitably configured then logging calls made |
| in library code will send output to those handlers, as normal. |
| |
| A do-nothing handler can be simply defined as follows:: |
| |
| import logging |
| |
| class NullHandler(logging.Handler): |
| def emit(self, record): |
| pass |
| |
| An instance of this handler should be added to the top-level logger of the |
| logging namespace used by the library. If all logging by a library *foo* is |
| done using loggers with names matching "foo.x.y", then the code:: |
| |
| import logging |
| |
| h = NullHandler() |
| logging.getLogger("foo").addHandler(h) |
| |
| should have the desired effect. If an organisation produces a number of |
| libraries, then the logger name specified can be "orgname.foo" rather than |
| just "foo". |
| |
| |
| Logging Levels |
| -------------- |
| |
| The numeric values of logging levels are given in the following table. These are |
| primarily of interest if you want to define your own levels, and need them to |
| have specific values relative to the predefined levels. If you define a level |
| with the same numeric value, it overwrites the predefined value; the predefined |
| name is lost. |
| |
| +--------------+---------------+ |
| 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. |
| |
| .. versionchanged:: 2.5 |
| *extra* was added. |
| |
| |
n | .. method:: XXX Class.info(msg[, *args[, **kwargs]]) |
n | .. method:: Logger.info(msg[, *args[, **kwargs]]) |
| |
| Logs a message with level :const:`INFO` on this logger. The arguments are |
| interpreted as for :meth:`debug`. |
| |
| |
n | .. method:: XXX Class.warning(msg[, *args[, **kwargs]]) |
n | .. method:: Logger.warning(msg[, *args[, **kwargs]]) |
| |
| Logs a message with level :const:`WARNING` on this logger. The arguments are |
| interpreted as for :meth:`debug`. |
| |
| |
n | .. method:: XXX Class.error(msg[, *args[, **kwargs]]) |
n | .. method:: Logger.error(msg[, *args[, **kwargs]]) |
| |
| Logs a message with level :const:`ERROR` on this logger. The arguments are |
| interpreted as for :meth:`debug`. |
| |
| |
n | .. method:: XXX Class.critical(msg[, *args[, **kwargs]]) |
n | .. method:: Logger.critical(msg[, *args[, **kwargs]]) |
| |
| Logs a message with level :const:`CRITICAL` on this logger. The arguments are |
| interpreted as for :meth:`debug`. |
| |
| |
n | .. method:: XXX Class.log(lvl, msg[, *args[, **kwargs]]) |
n | .. method:: Logger.log(lvl, msg[, *args[, **kwargs]]) |
| |
| Logs a message with integer level *lvl* on this logger. The other arguments are |
| interpreted as for :meth:`debug`. |
| |
| |
n | .. method:: XXX Class.exception(msg[, *args]) |
n | .. method:: Logger.exception(msg[, *args]) |
| |
| Logs a message with level :const:`ERROR` on this logger. The arguments are |
| interpreted as for :meth:`debug`. Exception info is added to the logging |
| message. This method should only be called from an exception handler. |
| |
| |
n | .. method:: XXX Class.addFilter(filt) |
n | .. method:: Logger.addFilter(filt) |
| |
| Adds the specified filter *filt* to this logger. |
| |
| |
n | .. method:: XXX Class.removeFilter(filt) |
n | .. method:: Logger.removeFilter(filt) |
| |
| Removes the specified filter *filt* from this logger. |
| |
| |
n | .. method:: XXX Class.filter(record) |
n | .. method:: Logger.filter(record) |
| |
| Applies this logger's filters to the record and returns a true value if the |
| record is to be processed. |
| |
| |
n | .. method:: XXX Class.addHandler(hdlr) |
n | .. method:: Logger.addHandler(hdlr) |
| |
| Adds the specified handler *hdlr* to this logger. |
| |
| |
n | .. method:: XXX Class.removeHandler(hdlr) |
n | .. method:: Logger.removeHandler(hdlr) |
| |
| Removes the specified handler *hdlr* from this logger. |
| |
| |
n | .. method:: XXX Class.findCaller() |
n | .. method:: Logger.findCaller() |
| |
n | Finds the caller's source filename and line number. Returns the filename and |
n | Finds the caller's source filename and line number. Returns the filename, line |
| line number as a 2-element tuple. |
| number and function name as a 3-element tuple. |
| |
n | .. versionchanged:: 2.4 |
| The function name was added. In earlier versions, the filename and line number |
| were returned as a 2-element tuple.. |
| |
n | |
| .. method:: XXX Class.handle(record) |
| .. method:: Logger.handle(record) |
| |
| Handles a record by passing it to all handlers associated with this logger and |
| its ancestors (until a false value of *propagate* is found). This method is used |
| for unpickled records received from a socket, as well as those created locally. |
| Logger-level filtering is applied using :meth:`filter`. |
| |
| |
n | .. method:: XXX Class.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func, extra) |
n | .. method:: Logger.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. |
| |
| .. versionchanged:: 2.5 |
| *func* and *extra* were added. |
| |
| |
| |
| As you can see, the DEBUG message only shows up in the file. The other messages |
| are sent to both destinations. |
| |
| This example uses console and file handlers, but you can use any number and |
| combination of handlers you choose. |
| |
| |
n | .. _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. |
| |
| An easy way in which you can pass contextual information to be output along |
| with logging event information is to use the :class:`LoggerAdapter` class. |
| This class is designed to look like a :class:`Logger`, so that you can call |
| :meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, |
| :meth:`exception`, :meth:`critical` and :meth:`log`. These methods have the |
| same signatures as their counterparts in :class:`Logger`, so you can use the |
| two types of instances interchangeably. |
| |
| When you create an instance of :class:`LoggerAdapter`, you pass it a |
| :class:`Logger` instance and a dict-like object which contains your contextual |
| information. When you call one of the logging methods on an instance of |
| :class:`LoggerAdapter`, it delegates the call to the underlying instance of |
| :class:`Logger` passed to its constructor, and arranges to pass the contextual |
| information in the delegated call. Here's a snippet from the code of |
| :class:`LoggerAdapter`:: |
| |
| def debug(self, msg, *args, **kwargs): |
| """ |
| Delegate a debug call to the underlying logger, after adding |
| contextual information from this adapter instance. |
| """ |
| msg, kwargs = self.process(msg, kwargs) |
| self.logger.debug(msg, *args, **kwargs) |
| |
| The :meth:`process` method of :class:`LoggerAdapter` is where the contextual |
| information is added to the logging output. It's passed the message and |
| keyword arguments of the logging call, and it passes back (potentially) |
| modified versions of these to use in the call to the underlying logger. The |
| default implementation of this method leaves the message alone, but inserts |
| an "extra" key in the keyword argument whose value is the dict-like object |
| passed to the constructor. Of course, if you had passed an "extra" keyword |
| argument in the call to the adapter, it will be silently overwritten. |
| |
| The advantage of using "extra" is that the values in the dict-like object are |
| merged into the :class:`LogRecord` instance's __dict__, allowing you to use |
| customized strings with your :class:`Formatter` instances which know about |
| the keys of the dict-like object. If you need a different method, e.g. if you |
| want to prepend or append the contextual information to the message string, |
| you just need to subclass :class:`LoggerAdapter` and override :meth:`process` |
| to do what you need. Here's an example script which uses this class, which |
| also illustrates what dict-like behaviour is needed from an arbitrary |
| "dict-like" object for use in the constructor:: |
| |
| import logging |
| |
| class ConnInfo: |
| """ |
| An example class which shows how an arbitrary class can be used as |
| the 'extra' context information repository passed to a LoggerAdapter. |
| """ |
| |
| def __getitem__(self, name): |
| """ |
| To allow this instance to look like a dict. |
| """ |
| from random import choice |
| if name == "ip": |
| result = choice(["127.0.0.1", "192.168.0.1"]) |
| elif name == "user": |
| result = choice(["jim", "fred", "sheila"]) |
| else: |
| result = self.__dict__.get(name, "?") |
| return result |
| |
| def __iter__(self): |
| """ |
| To allow iteration over keys, which will be merged into |
| the LogRecord dict before formatting and output. |
| """ |
| keys = ["ip", "user"] |
| keys.extend(self.__dict__.keys()) |
| return keys.__iter__() |
| |
| if __name__ == "__main__": |
| from random import choice |
| levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL) |
| a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"), |
| { "ip" : "123.231.231.123", "user" : "sheila" }) |
| logging.basicConfig(level=logging.DEBUG, |
| format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s") |
| a1.debug("A debug message") |
| a1.info("An info message with %s", "some parameters") |
| a2 = logging.LoggerAdapter(logging.getLogger("d.e.f"), ConnInfo()) |
| for x in range(10): |
| lvl = choice(levels) |
| lvlname = logging.getLevelName(lvl) |
| a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters") |
| |
| When this script is run, the output should look something like this:: |
| |
| 2008-01-18 14:49:54,023 a.b.c DEBUG IP: 123.231.231.123 User: sheila A debug message |
| 2008-01-18 14:49:54,023 a.b.c INFO IP: 123.231.231.123 User: sheila An info message with some parameters |
| 2008-01-18 14:49:54,023 d.e.f CRITICAL IP: 192.168.0.1 User: jim A message at CRITICAL level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: jim A message at INFO level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: fred A message at ERROR level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: sheila A message at ERROR level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: jim A message at WARNING level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: fred A message at INFO level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters |
| 2008-01-18 14:49:54,033 d.e.f WARNING IP: 127.0.0.1 User: jim A message at WARNING level with 2 parameters |
| |
| .. versionadded:: 2.6 |
| |
| The :class:`LoggerAdapter` class was not present in previous versions. |
| |
| |
| .. _network-logging: |
| |
| Sending and receiving logging events across a network |
| ----------------------------------------------------- |
| |
| Let's say you want to send logging events across a network, and handle them at |
| the receiving end. A simple way of doing this is attaching a |
| :class:`SocketHandler` instance to the root logger at the sending end:: |
| --------------- |
| |
| Handlers have the following attributes and methods. Note that :class:`Handler` |
| is never instantiated directly; this class acts as a base for more useful |
| subclasses. However, the :meth:`__init__` method in subclasses needs to call |
| :meth:`Handler.__init__`. |
| |
| |
n | .. method:: XXX Class.__init__(level=NOTSET) |
n | .. method:: Handler.__init__(level=NOTSET) |
| |
| Initializes the :class:`Handler` instance by setting its level, setting the list |
| of filters to the empty list and creating a lock (using :meth:`createLock`) for |
| serializing access to an I/O mechanism. |
| |
| |
n | .. method:: XXX Class.createLock() |
n | .. method:: Handler.createLock() |
| |
| Initializes a thread lock which can be used to serialize access to underlying |
| I/O functionality which may not be threadsafe. |
| |
| |
n | .. method:: XXX Class.acquire() |
n | .. method:: Handler.acquire() |
| |
| Acquires the thread lock created with :meth:`createLock`. |
| |
| |
n | .. method:: XXX Class.release() |
n | .. method:: Handler.release() |
| |
| Releases the thread lock acquired with :meth:`acquire`. |
| |
| |
n | .. method:: XXX Class.setLevel(lvl) |
n | .. method:: Handler.setLevel(lvl) |
| |
| Sets the threshold for this handler to *lvl*. Logging messages which are less |
| severe than *lvl* will be ignored. When a handler is created, the level is set |
| to :const:`NOTSET` (which causes all messages to be processed). |
| |
| |
n | .. method:: XXX Class.setFormatter(form) |
n | .. method:: Handler.setFormatter(form) |
| |
| Sets the :class:`Formatter` for this handler to *form*. |
| |
| |
n | .. method:: XXX Class.addFilter(filt) |
n | .. method:: Handler.addFilter(filt) |
| |
| Adds the specified filter *filt* to this handler. |
| |
| |
n | .. method:: XXX Class.removeFilter(filt) |
n | .. method:: Handler.removeFilter(filt) |
| |
| Removes the specified filter *filt* from this handler. |
| |
| |
n | .. method:: XXX Class.filter(record) |
n | .. method:: Handler.filter(record) |
| |
| Applies this handler's filters to the record and returns a true value if the |
| record is to be processed. |
| |
| |
n | .. method:: XXX Class.flush() |
n | .. method:: Handler.flush() |
| |
| Ensure all logging output has been flushed. This version does nothing and is |
| intended to be implemented by subclasses. |
| |
| |
n | .. method:: XXX Class.close() |
n | .. method:: Handler.close() |
| |
n | Tidy up any resources used by the handler. This version does nothing and is |
n | Tidy up any resources used by the handler. This version does no output but |
| intended to be implemented by subclasses. |
| removes the handler from an internal list of handlers which is closed when |
| :func:`shutdown` is called. Subclasses should ensure that this gets called |
| from overridden :meth:`close` methods. |
| |
| |
n | .. method:: XXX Class.handle(record) |
n | .. method:: Handler.handle(record) |
| |
| Conditionally emits the specified logging record, depending on filters which may |
| have been added to the handler. Wraps the actual emission of the record with |
| acquisition/release of the I/O thread lock. |
| |
| |
n | .. method:: XXX Class.handleError(record) |
n | .. method:: Handler.handleError(record) |
| |
| This method should be called from handlers when an exception is encountered |
| during an :meth:`emit` call. By default it does nothing, which means that |
| exceptions get silently ignored. This is what is mostly wanted for a logging |
| system - most users will not care about errors in the logging system, they are |
| more interested in application errors. You could, however, replace this with a |
| custom handler if you wish. The specified record is the one which was being |
| processed when the exception occurred. |
| |
| |
n | .. method:: XXX Class.format(record) |
n | .. method:: Handler.format(record) |
| |
| Do formatting for a record - if a formatter is set, use it. Otherwise, use the |
| default formatter for the module. |
| |
| |
n | .. method:: XXX Class.emit(record) |
n | .. method:: Handler.emit(record) |
| |
| Do whatever it takes to actually log the specified logging record. This version |
| is intended to be implemented by subclasses and so raises a |
| :exc:`NotImplementedError`. |
| |
| |
| StreamHandler |
| ^^^^^^^^^^^^^ |
| |
n | .. module:: logging.handlers |
| |
| The :class:`StreamHandler` class, located in the core :mod:`logging` package, |
n | sends logging output to streams such as *sys.stdout*, *sys.stderr* or any file- |
n | sends logging output to streams such as *sys.stdout*, *sys.stderr* or any |
| like object (or, more precisely, any object which supports :meth:`write` and |
| file-like object (or, more precisely, any object which supports :meth:`write` |
| :meth:`flush` methods). |
| and :meth:`flush` methods). |
| |
| |
| .. class:: StreamHandler([strm]) |
| |
| Returns a new instance of the :class:`StreamHandler` class. If *strm* is |
| specified, the instance will use it for logging output; otherwise, *sys.stderr* |
| will be used. |
| |
| |
n | .. method:: StreamHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | If a formatter is specified, it is used to format the record. The record is then |
n | If a formatter is specified, it is used to format the record. The record |
| written to the stream with a trailing newline. If exception information is |
| is then written to the stream with a trailing newline. If exception |
| present, it is formatted using :func:`traceback.print_exception` and appended to |
| information is present, it is formatted using |
| the stream. |
| :func:`traceback.print_exception` and appended to the stream. |
| |
| |
n | .. method:: StreamHandler.flush() |
n | .. method:: flush() |
| |
n | Flushes the stream by calling its :meth:`flush` method. Note that the |
n | Flushes the stream by calling its :meth:`flush` method. Note that the |
| :meth:`close` method is inherited from :class:`Handler` and so does nothing, so |
| :meth:`close` method is inherited from :class:`Handler` and so does |
| an explicit :meth:`flush` call may be needed at times. |
| no output, so an explicit :meth:`flush` call may be needed at times. |
| |
| |
| FileHandler |
| ^^^^^^^^^^^ |
| |
| The :class:`FileHandler` class, located in the core :mod:`logging` package, |
| sends logging output to a disk file. It inherits the output functionality from |
| :class:`StreamHandler`. |
| |
| |
n | .. class:: FileHandler(filename[, mode]) |
n | .. class:: FileHandler(filename[, mode[, encoding[, delay]]]) |
| |
| Returns a new instance of the :class:`FileHandler` class. The specified file is |
| opened and used as the stream for logging. If *mode* is not specified, |
n | :const:`'a'` is used. By default, the file grows indefinitely. |
n | :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file |
| with that encoding. If *delay* is true, then file opening is deferred until the |
| first call to :meth:`emit`. By default, the file grows indefinitely. |
| |
| |
n | .. method:: FileHandler.close() |
n | .. method:: close() |
| |
n | Closes the file. |
n | Closes the file. |
| |
| |
n | .. method:: FileHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | Outputs the record to the file. |
n | Outputs the record to the file. |
| |
| |
| See :ref:`library-config` for more information on how to use |
| :class:`NullHandler`. |
| |
| WatchedFileHandler |
| ^^^^^^^^^^^^^^^^^^ |
| |
| .. versionadded:: 2.6 |
| |
| The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers` |
| module, is a :class:`FileHandler` which watches the file it is logging to. If |
| the file changes, it is closed and reopened using the file name. |
| |
| A file change can happen because of usage of programs such as *newsyslog* and |
| *logrotate* which perform log file rotation. This handler, intended for use |
| under Unix/Linux, watches the file to see if it has changed since the last emit. |
| (A file is deemed to have changed if its device or inode have changed.) If the |
| file has changed, the old file stream is closed, and the file opened to get a |
| new stream. |
| |
| This handler is not appropriate for use under Windows, because under Windows |
| open log files cannot be moved or renamed - logging opens the files with |
| exclusive locks - and so there is no need for such a handler. Furthermore, |
| *ST_INO* is not supported under Windows; :func:`stat` always returns zero for |
| this value. |
| |
| |
| .. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]]) |
| |
| Returns a new instance of the :class:`WatchedFileHandler` class. The specified |
| file is opened and used as the stream for logging. If *mode* is not specified, |
| :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file |
| with that encoding. If *delay* is true, then file opening is deferred until the |
| first call to :meth:`emit`. By default, the file grows indefinitely. |
| |
| |
| .. method:: emit(record) |
| |
| Outputs the record to the file, but first checks to see if the file has |
| changed. If it has, the existing stream is flushed and closed and the |
| file opened again, before outputting the record to the file. |
| |
| |
| RotatingFileHandler |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers` |
| module, supports rotation of disk log files. |
| |
| |
n | .. class:: RotatingFileHandler(filename[, mode[, maxBytes[, backupCount]]]) |
n | .. class:: RotatingFileHandler(filename[, mode[, maxBytes[, backupCount[, encoding[, delay]]]]]) |
| |
| Returns a new instance of the :class:`RotatingFileHandler` class. The specified |
| file is opened and used as the stream for logging. If *mode* is not specified, |
n | ``'a'`` is used. By default, the file grows indefinitely. |
n | ``'a'`` is used. If *encoding* is not *None*, it is used to open the file |
| with that encoding. If *delay* is true, then file opening is deferred until the |
| first call to :meth:`emit`. By default, the file grows indefinitely. |
| |
| You can use the *maxBytes* and *backupCount* values to allow the file to |
| :dfn:`rollover` at a predetermined size. When the size is about to be exceeded, |
| the file is closed and a new file is silently opened for output. Rollover occurs |
| whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is |
| zero, rollover never occurs. If *backupCount* is non-zero, the system will save |
| old log files by appending the extensions ".1", ".2" etc., to the filename. For |
| example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you |
| would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to |
| :file:`app.log.5`. The file being written to is always :file:`app.log`. When |
| this file is filled, it is closed and renamed to :file:`app.log.1`, and if files |
| :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to |
| :file:`app.log.2`, :file:`app.log.3` etc. respectively. |
| |
| |
n | .. method:: RotatingFileHandler.doRollover() |
n | .. method:: doRollover() |
| |
n | Does a rollover, as described above. |
n | Does a rollover, as described above. |
| |
| |
n | .. method:: RotatingFileHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | Outputs the record to the file, catering for rollover as described previously. |
n | Outputs the record to the file, catering for rollover as described |
| previously. |
| |
| |
| TimedRotatingFileHandler |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The :class:`TimedRotatingFileHandler` class, located in the |
| :mod:`logging.handlers` module, supports rotation of disk log files at certain |
| timed intervals. |
| |
| |
n | .. class:: TimedRotatingFileHandler(filename [,when [,interval [,backupCount]]]) |
n | .. class:: TimedRotatingFileHandler(filename [,when [,interval [,backupCount[, encoding[, delay[, utc]]]]]]) |
| |
| Returns a new instance of the :class:`TimedRotatingFileHandler` class. The |
| specified file is opened and used as the stream for logging. On rotating it also |
| sets the filename suffix. Rotating happens based on the product of *when* and |
| *interval*. |
| |
| You can use the *when* to specify the type of *interval*. The list of possible |
n | values is, note that they are not case sensitive: |
n | values is below. Note that they are not case sensitive. |
| |
n | +----------+-----------------------+ |
n | +----------------+-----------------------+ |
| | Value | Type of interval | |
| | Value | Type of interval | |
| +==========+=======================+ |
| +================+=======================+ |
| | S | Seconds | |
| | ``'S'`` | Seconds | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| | M | Minutes | |
| | ``'M'`` | Minutes | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| | H | Hours | |
| | ``'H'`` | Hours | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| | D | Days | |
| | ``'D'`` | Days | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| | W | Week day (0=Monday) | |
| | ``'W'`` | Week day (0=Monday) | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| | midnight | Roll over at midnight | |
| | ``'midnight'`` | Roll over at midnight | |
| +----------+-----------------------+ |
| +----------------+-----------------------+ |
| |
n | If *backupCount* is non-zero, the system will save old log files by appending |
n | The system will save old log files by appending extensions to the filename. |
| extensions to the filename. The extensions are date-and-time based, using the |
| The extensions are date-and-time based, using the strftime format |
| strftime format ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on |
| ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the |
| the rollover interval. At most *backupCount* files will be kept, and if more |
| rollover interval. |
| would be created when rollover occurs, the oldest one is deleted. |
| If the *utc* argument is true, times in UTC will be used; otherwise |
| local time is used. |
| |
n | If *backupCount* is nonzero, at most *backupCount* files |
| will be kept, and if more would be created when rollover occurs, the oldest |
| one is deleted. The deletion logic uses the interval to determine which |
| files to delete, so changing the interval may leave old files lying around. |
| |
n | .. method:: TimedRotatingFileHandler.doRollover() |
| |
n | .. method:: doRollover() |
| |
| Does a rollover, as described above. |
| Does a rollover, as described above. |
| |
| |
n | .. method:: TimedRotatingFileHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | Outputs the record to the file, catering for rollover as described above. |
n | Outputs the record to the file, catering for rollover as described above. |
| |
| |
| SocketHandler |
| ^^^^^^^^^^^^^ |
| |
| The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module, |
| sends logging output to a network socket. The base class uses a TCP socket. |
| |
| |
| .. class:: SocketHandler(host, port) |
| |
| Returns a new instance of the :class:`SocketHandler` class intended to |
| communicate with a remote machine whose address is given by *host* and *port*. |
| |
| |
n | .. method:: SocketHandler.close() |
n | .. method:: close() |
| |
n | Closes the socket. |
n | Closes the socket. |
| |
| |
n | .. method:: SocketHandler.handleError() |
n | .. method:: emit() |
| |
n | |
| .. method:: SocketHandler.emit() |
| |
| Pickles the record's attribute dictionary and writes it to the socket in binary |
| Pickles the record's attribute dictionary and writes it to the socket in |
| format. If there is an error with the socket, silently drops the packet. If the |
| binary format. If there is an error with the socket, silently drops the |
| connection was previously lost, re-establishes the connection. To unpickle the |
| packet. If the connection was previously lost, re-establishes the |
| record at the receiving end into a :class:`LogRecord`, use the |
| connection. To unpickle the record at the receiving end into a |
| :func:`makeLogRecord` function. |
| :class:`LogRecord`, use the :func:`makeLogRecord` function. |
| |
| |
n | .. method:: SocketHandler.handleError() |
n | .. method:: handleError() |
| |
n | Handles an error which has occurred during :meth:`emit`. The most likely cause |
n | Handles an error which has occurred during :meth:`emit`. The most likely |
| is a lost connection. Closes the socket so that we can retry on the next event. |
| cause is a lost connection. Closes the socket so that we can retry on the |
| next event. |
| |
| |
n | .. method:: SocketHandler.makeSocket() |
n | .. method:: makeSocket() |
| |
n | This is a factory method which allows subclasses to define the precise type of |
n | This is a factory method which allows subclasses to define the precise |
| socket they want. The default implementation creates a TCP socket |
| type of socket they want. The default implementation creates a TCP socket |
| (:const:`socket.SOCK_STREAM`). |
| (:const:`socket.SOCK_STREAM`). |
| |
| |
n | .. method:: SocketHandler.makePickle(record) |
n | .. method:: makePickle(record) |
| |
n | Pickles the record's attribute dictionary in binary format with a length prefix, |
n | Pickles the record's attribute dictionary in binary format with a length |
| and returns it ready for transmission across the socket. |
| prefix, and returns it ready for transmission across the socket. |
| |
| |
n | .. method:: SocketHandler.send(packet) |
n | .. method:: send(packet) |
| |
n | Send a pickled string *packet* to the socket. This function allows for partial |
n | Send a pickled string *packet* to the socket. This function allows for |
| sends which can happen when the network is busy. |
| partial sends which can happen when the network is busy. |
| |
| |
| DatagramHandler |
| ^^^^^^^^^^^^^^^ |
| |
| The :class:`DatagramHandler` class, located in the :mod:`logging.handlers` |
| module, inherits from :class:`SocketHandler` to support sending logging messages |
| over UDP sockets. |
| |
| |
| .. class:: DatagramHandler(host, port) |
| |
| Returns a new instance of the :class:`DatagramHandler` class intended to |
| communicate with a remote machine whose address is given by *host* and *port*. |
| |
| |
n | .. method:: DatagramHandler.emit() |
n | .. method:: emit() |
| |
n | Pickles the record's attribute dictionary and writes it to the socket in binary |
n | Pickles the record's attribute dictionary and writes it to the socket in |
| format. If there is an error with the socket, silently drops the packet. To |
| binary format. If there is an error with the socket, silently drops the |
| unpickle the record at the receiving end into a :class:`LogRecord`, use the |
| packet. To unpickle the record at the receiving end into a |
| :func:`makeLogRecord` function. |
| :class:`LogRecord`, use the :func:`makeLogRecord` function. |
| |
| |
n | .. method:: DatagramHandler.makeSocket() |
n | .. method:: makeSocket() |
| |
n | The factory method of :class:`SocketHandler` is here overridden to create a UDP |
n | The factory method of :class:`SocketHandler` is here overridden to create |
| socket (:const:`socket.SOCK_DGRAM`). |
| a UDP socket (:const:`socket.SOCK_DGRAM`). |
| |
| |
n | .. method:: DatagramHandler.send(s) |
n | .. method:: send(s) |
| |
n | Send a pickled string to a socket. |
n | Send a pickled string to a socket. |
| |
| |
| SysLogHandler |
| ^^^^^^^^^^^^^ |
| |
| The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module, |
| supports sending logging messages to a remote or local Unix syslog. |
| |
| |
| .. class:: SysLogHandler([address[, facility]]) |
| |
| Returns a new instance of the :class:`SysLogHandler` class intended to |
| communicate with a remote Unix machine whose address is given by *address* in |
| the form of a ``(host, port)`` tuple. If *address* is not specified, |
n | ``('localhost', 514)`` is used. The address is used to open a UDP socket. If |
n | ``('localhost', 514)`` is used. The address is used to open a UDP socket. An |
| *facility* is not specified, :const:`LOG_USER` is used. |
| alternative to providing a ``(host, port)`` tuple is providing an address as a |
| string, for example "/dev/log". In this case, a Unix domain socket is used to |
| send the message to the syslog. If *facility* is not specified, |
| :const:`LOG_USER` is used. |
| |
| |
n | .. method:: SysLogHandler.close() |
n | .. method:: close() |
| |
n | Closes the socket to the remote host. |
n | Closes the socket to the remote host. |
| |
| |
n | .. method:: SysLogHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | The record is formatted, and then sent to the syslog server. If exception |
n | The record is formatted, and then sent to the syslog server. If exception |
| information is present, it is *not* sent to the server. |
| information is present, it is *not* sent to the server. |
| |
| |
n | .. method:: SysLogHandler.encodePriority(facility, priority) |
n | .. method:: encodePriority(facility, priority) |
| |
n | Encodes the facility and priority into an integer. You can pass in strings or |
n | Encodes the facility and priority into an integer. You can pass in strings |
| integers - if strings are passed, internal mapping dictionaries are used to |
| or integers - if strings are passed, internal mapping dictionaries are |
| convert them to integers. |
| used to convert them to integers. |
| |
| |
| NTEventLogHandler |
| ^^^^^^^^^^^^^^^^^ |
| |
| The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers` |
| module, supports sending logging messages to a local Windows NT, Windows 2000 or |
| Windows XP event log. Before you can use it, you need Mark Hammond's Win32 |
| placeholder message definitions. Note that use of these placeholders will make |
| your event logs big, as the entire message source is held in the log. If you |
| want slimmer logs, you have to pass in the name of your own .dll or .exe which |
| contains the message definitions you want to use in the event log). The |
| *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and |
| defaults to ``'Application'``. |
| |
| |
n | .. method:: NTEventLogHandler.close() |
n | .. method:: close() |
| |
n | At this point, you can remove the application name from the registry as a source |
n | At this point, you can remove the application name from the registry as a |
| of event log entries. However, if you do this, you will not be able to see the |
| source of event log entries. However, if you do this, you will not be able |
| events as you intended in the Event Log Viewer - it needs to be able to access |
| to see the events as you intended in the Event Log Viewer - it needs to be |
| the registry to get the .dll name. The current version does not do this (in fact |
| able to access the registry to get the .dll name. The current version does |
| it doesn't do anything). |
| not do this. |
| |
| |
n | .. method:: NTEventLogHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | Determines the message ID, event category and event type, and then logs the |
n | Determines the message ID, event category and event type, and then logs |
| message in the NT event log. |
| the message in the NT event log. |
| |
| |
n | .. method:: NTEventLogHandler.getEventCategory(record) |
n | .. method:: getEventCategory(record) |
| |
n | Returns the event category for the record. Override this if you want to specify |
n | Returns the event category for the record. Override this if you want to |
| your own categories. This version returns 0. |
| specify your own categories. This version returns 0. |
| |
| |
n | .. method:: NTEventLogHandler.getEventType(record) |
n | .. method:: getEventType(record) |
| |
n | Returns the event type for the record. Override this if you want to specify your |
n | Returns the event type for the record. Override this if you want to |
| own types. This version does a mapping using the handler's typemap attribute, |
| specify your own types. This version does a mapping using the handler's |
| which is set up in :meth:`__init__` to a dictionary which contains mappings for |
| typemap attribute, which is set up in :meth:`__init__` to a dictionary |
| :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, :const:`ERROR` and |
| which contains mappings for :const:`DEBUG`, :const:`INFO`, |
| :const:`CRITICAL`. If you are using your own levels, you will either need to |
| :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using |
| override this method or place a suitable dictionary in the handler's *typemap* |
| your own levels, you will either need to override this method or place a |
| attribute. |
| suitable dictionary in the handler's *typemap* attribute. |
| |
| |
n | .. method:: NTEventLogHandler.getMessageID(record) |
n | .. method:: getMessageID(record) |
| |
n | Returns the message ID for the record. If you are using your own messages, you |
n | Returns the message ID for the record. If you are using your own messages, |
| could do this by having the *msg* passed to the logger being an ID rather than a |
| you could do this by having the *msg* passed to the logger being an ID |
| format string. Then, in here, you could use a dictionary lookup to get the |
| rather than a format string. Then, in here, you could use a dictionary |
| message ID. This version returns 1, which is the base message ID in |
| lookup to get the message ID. This version returns 1, which is the base |
| :file:`win32service.pyd`. |
| message ID in :file:`win32service.pyd`. |
| |
| |
| SMTPHandler |
| ^^^^^^^^^^^ |
| |
| The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module, |
| supports sending logging messages to an email address via SMTP. |
| |
| |
n | .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject) |
n | .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject[, credentials]) |
| |
| Returns a new instance of the :class:`SMTPHandler` class. The instance is |
| initialized with the from and to addresses and subject line of the email. The |
| *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use |
| the (host, port) tuple format for the *mailhost* argument. If you use a string, |
n | the standard SMTP port is used. |
n | the standard SMTP port is used. If your SMTP server requires authentication, you |
| can specify a (username, password) tuple for the *credentials* argument. |
| |
n | .. versionchanged:: 2.6 |
| *credentials* was added. |
| |
n | |
| .. method:: SMTPHandler.emit(record) |
| .. method:: emit(record) |
| |
n | Formats the record and sends it to the specified addressees. |
n | Formats the record and sends it to the specified addressees. |
| |
| |
n | .. method:: SMTPHandler.getSubject(record) |
n | .. method:: getSubject(record) |
| |
n | If you want to specify a subject line which is record-dependent, override this |
n | If you want to specify a subject line which is record-dependent, override |
| method. |
| this method. |
| |
| |
| MemoryHandler |
| ^^^^^^^^^^^^^ |
| |
| The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module, |
| supports buffering of logging records in memory, periodically flushing them to a |
| :dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an |
| .. class:: HTTPHandler(host, url[, method]) |
| |
| Returns a new instance of the :class:`HTTPHandler` class. The instance is |
| initialized with a host address, url and HTTP method. The *host* can be of the |
| form ``host:port``, should you need to use a specific port number. If no |
| *method* is specified, ``GET`` is used. |
| |
| |
n | .. method:: HTTPHandler.emit(record) |
n | .. method:: emit(record) |
| |
n | Sends the record to the Web server as an URL-encoded dictionary. |
n | Sends the record to the Web server as an URL-encoded dictionary. |
| |
n | |
| .. _formatter-objects: |
| |
| Formatter Objects |
| ----------------- |
n | |
| .. currentmodule:: logging |
| |
| :class:`Formatter`\ s have the following attributes and methods. They are |
| responsible for converting a :class:`LogRecord` to (usually) a string which can |
| be interpreted by either a human or an external system. The base |
| :class:`Formatter` allows a formatting string to be specified. If none is |
| supplied, the default value of ``'%(message)s'`` is used. |
| |
| A Formatter can be initialized with a format string which makes use of knowledge |
| of the :class:`LogRecord` attributes - such as the default value mentioned above |
| making use of the fact that the user's message and arguments are pre-formatted |
| into a :class:`LogRecord`'s *message* attribute. This format string contains |
n | standard python %-style mapping keys. See section :ref:`typesseq-strings`, |
n | standard python %-style mapping keys. See section :ref:`string-formatting` |
| "String Formatting Operations," for more information on string formatting. |
| for more information on string formatting. |
| |
| Currently, the useful mapping keys in a :class:`LogRecord` are: |
| |
n | +--------------------+-----------------------------------------------+ |
n | +-------------------------+-----------------------------------------------+ |
| | Format | Description | |
| | Format | Description | |
| +====================+===============================================+ |
| +=========================+===============================================+ |
| | ``%(name)s`` | Name of the logger (logging channel). | |
| | ``%(name)s`` | Name of the logger (logging channel). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(levelno)s`` | Numeric logging level for the message | |
| | ``%(levelno)s`` | Numeric logging level for the message | |
| | | (:const:`DEBUG`, :const:`INFO`, | |
| | | (:const:`DEBUG`, :const:`INFO`, | |
| | | :const:`WARNING`, :const:`ERROR`, | |
| | | :const:`WARNING`, :const:`ERROR`, | |
| | | :const:`CRITICAL`). | |
| | | :const:`CRITICAL`). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(levelname)s`` | Text logging level for the message | |
| | ``%(levelname)s`` | Text logging level for the message | |
| | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, | |
| | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, | |
| | | ``'ERROR'``, ``'CRITICAL'``). | |
| | | ``'ERROR'``, ``'CRITICAL'``). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(pathname)s`` | Full pathname of the source file where the | |
| | ``%(pathname)s`` | Full pathname of the source file where the | |
| | | logging call was issued (if available). | |
| | | logging call was issued (if available). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(filename)s`` | Filename portion of pathname. | |
| | ``%(filename)s`` | Filename portion of pathname. | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(module)s`` | Module (name portion of filename). | |
| | ``%(module)s`` | Module (name portion of filename). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(funcName)s`` | Name of function containing the logging call. | |
| | ``%(funcName)s`` | Name of function containing the logging call. | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(lineno)d`` | Source line number where the logging call was | |
| | ``%(lineno)d`` | Source line number where the logging call was | |
| | | issued (if available). | |
| | | issued (if available). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(created)f`` | Time when the :class:`LogRecord` was created | |
| | ``%(created)f`` | Time when the :class:`LogRecord` was created | |
| | | (as returned by :func:`time.time`). | |
| | | (as returned by :func:`time.time`). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(asctime)s`` | Human-readable time when the | |
| | ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was | |
| | | :class:`LogRecord` was created. By default | |
| | | created, relative to the time the logging | |
| | | this is of the form "2003-07-08 16:49:45,896" | |
| | | module was loaded. | |
| | | (the numbers after the comma are millisecond | |
| | | portion of the time). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(msecs)d`` | Millisecond portion of the time when the | |
| | ``%(asctime)s`` | Human-readable time when the | |
| | | :class:`LogRecord` was created. | |
| | | :class:`LogRecord` was created. By default | |
| | | this is of the form "2003-07-08 16:49:45,896" | |
| | | (the numbers after the comma are millisecond | |
| | | portion of the time). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(thread)d`` | Thread ID (if available). | |
| | ``%(msecs)d`` | Millisecond portion of the time when the | |
| | | :class:`LogRecord` was created. | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(threadName)s`` | Thread name (if available). | |
| | ``%(thread)d`` | Thread ID (if available). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(process)d`` | Process ID (if available). | |
| | ``%(threadName)s`` | Thread name (if available). | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(message)s`` | The logged message, computed as ``msg % | |
| | ``%(process)d`` | Process ID (if available). | |
| | | args``. | |
| +--------------------+-----------------------------------------------+ |
| +-------------------------+-----------------------------------------------+ |
| | ``%(message)s`` | The logged message, computed as ``msg % | |
| | | args``. | |
| +-------------------------+-----------------------------------------------+ |
| |
| .. versionchanged:: 2.5 |
| *funcName* was added. |
| |
| |
| .. class:: Formatter([fmt[, datefmt]]) |
| |
| Returns a new instance of the :class:`Formatter` class. The instance is |
| initialized with a format string for the message as a whole, as well as a format |
| string for the date/time portion of a message. If no *fmt* is specified, |
| ``'%(message)s'`` is used. If no *datefmt* is specified, the ISO8601 date format |
| is used. |
| |
| |
n | .. method:: Formatter.format(record) |
n | .. method:: format(record) |
| |
n | The record's attribute dictionary is used as the operand to a string formatting |
n | The record's attribute dictionary is used as the operand to a string |
| operation. Returns the resulting string. Before formatting the dictionary, a |
| formatting operation. Returns the resulting string. Before formatting the |
| couple of preparatory steps are carried out. The *message* attribute of the |
| dictionary, a couple of preparatory steps are carried out. The *message* |
| record is computed using *msg* % *args*. If the formatting string contains |
| attribute of the record is computed using *msg* % *args*. If the |
| ``'(asctime)'``, :meth:`formatTime` is called to format the event time. If there |
| formatting string contains ``'(asctime)'``, :meth:`formatTime` is called |
| is exception information, it is formatted using :meth:`formatException` and |
| to format the event time. If there is exception information, it is |
| appended to the message. |
| formatted using :meth:`formatException` and appended to the message. Note |
| that the formatted exception information is cached in attribute |
| *exc_text*. This is useful because the exception information can be |
| pickled and sent across the wire, but you should be careful if you have |
| more than one :class:`Formatter` subclass which customizes the formatting |
| of exception information. In this case, you will have to clear the cached |
| value after a formatter has done its formatting, so that the next |
| formatter to handle the event doesn't use the cached value but |
| recalculates it afresh. |
| |
| |
n | .. method:: Formatter.formatTime(record[, datefmt]) |
n | .. method:: formatTime(record[, datefmt]) |
| |
n | This method should be called from :meth:`format` by a formatter which wants to |
n | This method should be called from :meth:`format` by a formatter which |
| make use of a formatted time. This method can be overridden in formatters to |
| wants to make use of a formatted time. This method can be overridden in |
| provide for any specific requirement, but the basic behavior is as follows: if |
| formatters to provide for any specific requirement, but the basic behavior |
| *datefmt* (a string) is specified, it is used with :func:`time.strftime` to |
| is as follows: if *datefmt* (a string) is specified, it is used with |
| format the creation time of the record. Otherwise, the ISO8601 format is used. |
| :func:`time.strftime` to format the creation time of the |
| The resulting string is returned. |
| record. Otherwise, the ISO8601 format is used. The resulting string is |
| returned. |
| |
| |
n | .. method:: Formatter.formatException(exc_info) |
n | .. method:: formatException(exc_info) |
| |
n | Formats the specified exception information (a standard exception tuple as |
n | Formats the specified exception information (a standard exception tuple as |
| returned by :func:`sys.exc_info`) as a string. This default implementation just |
| returned by :func:`sys.exc_info`) as a string. This default implementation |
| uses :func:`traceback.print_exception`. The resulting string is returned. |
| just uses :func:`traceback.print_exception`. The resulting string is |
| returned. |
| |
| |
| Filter Objects |
| -------------- |
| |
| :class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for |
| more sophisticated filtering than is provided by levels. The base filter class |
| only allows events which are below a certain point in the logger hierarchy. For |
| |
| .. class:: Filter([name]) |
| |
| Returns an instance of the :class:`Filter` class. If *name* is specified, it |
| names a logger which, together with its children, will have its events allowed |
| through the filter. If no name is specified, allows every event. |
| |
| |
n | .. method:: Filter.filter(record) |
n | .. method:: filter(record) |
| |
n | Is the specified record to be logged? Returns zero for no, nonzero for yes. If |
n | Is the specified record to be logged? Returns zero for no, nonzero for |
| deemed appropriate, the record may be modified in-place by this method. |
| yes. If deemed appropriate, the record may be modified in-place by this |
| method. |
| |
| |
| LogRecord Objects |
| ----------------- |
| |
| :class:`LogRecord` instances are created every time something is logged. They |
| contain all the information pertinent to the event being logged. The main |
| information passed in is in msg and args, which are combined using msg % args to |
| create the message field of the record. The record also includes information |
| such as when the record was created, the source line where the logging call was |
| made, and any exception information to be logged. |
| |
| |
n | .. class:: LogRecord(name, lvl, pathname, lineno, msg, args, exc_info) |
n | .. class:: LogRecord(name, lvl, pathname, lineno, msg, args, exc_info [, func]) |
| |
| Returns an instance of :class:`LogRecord` initialized with interesting |
| information. The *name* is the logger name; *lvl* is the numeric level; |
n | *pathname* is the absolute pathname of the source file in which the logging call |
n | *pathname* is the absolute pathname of the source file in which the logging |
| was made; *lineno* is the line number in that file where the logging call is |
| call was made; *lineno* is the line number in that file where the logging |
| found; *msg* is the user-supplied message (a format string); *args* is the tuple |
| call is found; *msg* is the user-supplied message (a format string); *args* |
| which, together with *msg*, makes up the user message; and *exc_info* is the |
| is the tuple which, together with *msg*, makes up the user message; and |
| exception tuple obtained by calling :func:`sys.exc_info()`\ (or :const:`None`, |
| *exc_info* is the exception tuple obtained by calling :func:`sys.exc_info` |
| if no exception information is available). |
| (or :const:`None`, if no exception information is available). The *func* is |
| the name of the function from which the logging call was made. If not |
| specified, it defaults to ``None``. |
| |
n | .. versionchanged:: 2.5 |
| *func* was added. |
| |
n | |
| .. method:: LogRecord.getMessage() |
| .. method:: getMessage() |
| |
n | Returns the message for this :class:`LogRecord` instance after merging any user- |
n | Returns the message for this :class:`LogRecord` instance after merging any |
| supplied arguments with the message. |
| user-supplied arguments with the message. |
| |
| |
| LoggerAdapter Objects |
| --------------------- |
| |
| .. versionadded:: 2.6 |
| |
| :class:`LoggerAdapter` instances are used to conveniently pass contextual |
| information into logging calls. For a usage example , see the section on |
| `adding contextual information to your logging output`__. |
| |
| __ context-info_ |
| |
| .. class:: LoggerAdapter(logger, extra) |
| |
| Returns an instance of :class:`LoggerAdapter` initialized with an |
| underlying :class:`Logger` instance and a dict-like object. |
| |
| .. method:: process(msg, kwargs) |
| |
| Modifies the message and/or keyword arguments passed to a logging call in |
| order to insert contextual information. This implementation takes the object |
| passed as *extra* to the constructor and adds it to *kwargs* using key |
| 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the |
| (possibly modified) versions of the arguments passed in. |
| |
| In addition to the above, :class:`LoggerAdapter` supports all the logging |
| methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`, |
| :meth:`error`, :meth:`exception`, :meth:`critical` and :meth:`log`. These |
| methods have the same signatures as their counterparts in :class:`Logger`, so |
| you can use the two types of instances interchangeably. |
| |
| |
| Thread Safety |
| ------------- |
| |
| The logging module is intended to be thread-safe without any special work |
| needing to be done by its clients. It achieves this though using threading |
| locks; there is one lock to serialize access to the module's shared data, and |
| Sections which specify formatter configuration are typified by the following. :: |
| |
| [formatter_form01] |
| format=F1 %(asctime)s %(levelname)s %(message)s |
| datefmt= |
| class=logging.Formatter |
| |
| The ``format`` entry is the overall format string, and the ``datefmt`` entry is |
n | the :func:`strftime`\ -compatible date/time format string. If empty, the package |
n | the :func:`strftime`\ -compatible date/time format string. If empty, the |
| substitutes ISO8601 format date/times, which is almost equivalent to specifying |
| package substitutes ISO8601 format date/times, which is almost equivalent to |
| the date format string "The ISO8601 format also specifies milliseconds, which |
| specifying the date format string ``"%Y-%m-%d %H:%M:%S"``. The ISO8601 format |
| are appended to the result of using the above format string, with a comma |
| also specifies milliseconds, which are appended to the result of using the above |
| separator. An example time in ISO8601 format is ``2003-01-23 00:29:50,411``. |
| format string, with a comma separator. An example time in ISO8601 format is |
| |
| ``2003-01-23 00:29:50,411``. |
| .. % Y-%m-%d %H:%M:%S". |
| |
| The ``class`` entry is optional. It indicates the name of the formatter's class |
| (as a dotted module and class name.) This option is useful for instantiating a |
| :class:`Formatter` subclass. Subclasses of :class:`Formatter` can present |
| exception tracebacks in an expanded or condensed format. |
| |
t | |
| Configuration server example |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Here is an example of a module using the logging configuration server:: |
| |
| import logging |
| import logging.config |
| import time |
| import os |
| |
| # read initial config file |
| logging.config.fileConfig("logging.conf") |
| |
| # create and start listener on port 9999 |
| t = logging.config.listen(9999) |
| t.start() |
| |
| logger = logging.getLogger("simpleExample") |
| |
| try: |
| # loop through logging calls to see the difference |
| # new configurations make, until Ctrl+C is pressed |
| while True: |
| logger.debug("debug message") |
| logger.info("info message") |
| logger.warn("warn message") |
| logger.error("error message") |
| logger.critical("critical message") |
| time.sleep(5) |
| except KeyboardInterrupt: |
| # cleanup |
| logging.config.stopListening() |
| t.join() |
| |
| And here is a script that takes a filename and sends that file to the server, |
| properly preceded with the binary-encoded length, as the new logging |
| configuration:: |
| |
| #!/usr/bin/env python |
| import socket, sys, struct |
| |
| data_to_send = open(sys.argv[1], "r").read() |
| |
| HOST = 'localhost' |
| PORT = 9999 |
| s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| print "connecting..." |
| s.connect((HOST, PORT)) |
| print "sending config..." |
| s.send(struct.pack(">L", len(data_to_send))) |
| s.send(data_to_send) |
| s.close() |
| print "complete" |
| |
| |
| More examples |
| ------------- |
| |
| Multiple handlers and formatters |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Loggers are plain Python objects. The :func:`addHandler` method has no minimum |
| or maximum quota for the number of handlers you may add. Sometimes it will be |
| beneficial for an application to log all messages of all severities to a text |
| file while simultaneously logging errors or above to the console. To set this |
| up, simply configure the appropriate handlers. The logging calls in the |
| application code will remain unchanged. Here is a slight modification to the |
| previous simple module-based configuration example:: |
| |
| import logging |
| |
| logger = logging.getLogger("simple_example") |
| logger.setLevel(logging.DEBUG) |
| # create file handler which logs even debug messages |
| fh = logging.FileHandler("spam.log") |
| fh.setLevel(logging.DEBUG) |
| # create console handler with a higher log level |
| ch = logging.StreamHandler() |
| ch.setLevel(logging.ERROR) |
| # create formatter and add it to the handlers |
| formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s") |
| ch.setFormatter(formatter) |
| fh.setFormatter(formatter) |
| # add the handlers to logger |
| logger.addHandler(ch) |
| logger.addHandler(fh) |
| |
| # "application" code |
| logger.debug("debug message") |
| logger.info("info message") |
| logger.warn("warn message") |
| logger.error("error message") |
| logger.critical("critical message") |
| |
| Notice that the "application" code does not care about multiple handlers. All |
| that changed was the addition and configuration of a new handler named *fh*. |
| |
| The ability to create new handlers with higher- or lower-severity filters can be |
| very helpful when writing and testing an application. Instead of using many |
| ``print`` statements for debugging, use ``logger.debug``: Unlike the print |
| statements, which you will have to delete or comment out later, the logger.debug |
| statements can remain intact in the source code and remain dormant until you |
| need them again. At that time, the only change that needs to happen is to |
| modify the severity level of the logger and/or handler to debug. |
| |
| |
| Using logging in multiple modules |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| It was mentioned above that multiple calls to |
| ``logging.getLogger('someLogger')`` return a reference to the same logger |
| object. This is true not only within the same module, but also across modules |
| as long as it is in the same Python interpreter process. It is true for |
| references to the same object; additionally, application code can define and |
| configure a parent logger in one module and create (but not configure) a child |
| logger in a separate module, and all logger calls to the child will pass up to |
| the parent. Here is a main module:: |
| |
| import logging |
| import auxiliary_module |
| |
| # create logger with "spam_application" |
| logger = logging.getLogger("spam_application") |
| logger.setLevel(logging.DEBUG) |
| # create file handler which logs even debug messages |
| fh = logging.FileHandler("spam.log") |
| fh.setLevel(logging.DEBUG) |
| # create console handler with a higher log level |
| ch = logging.StreamHandler() |
| ch.setLevel(logging.ERROR) |
| # create formatter and add it to the handlers |
| formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s") |
| fh.setFormatter(formatter) |
| ch.setFormatter(formatter) |
| # add the handlers to the logger |
| logger.addHandler(fh) |
| logger.addHandler(ch) |
| |
| logger.info("creating an instance of auxiliary_module.Auxiliary") |
| a = auxiliary_module.Auxiliary() |
| logger.info("created an instance of auxiliary_module.Auxiliary") |
| logger.info("calling auxiliary_module.Auxiliary.do_something") |
| a.do_something() |
| logger.info("finished auxiliary_module.Auxiliary.do_something") |
| logger.info("calling auxiliary_module.some_function()") |
| auxiliary_module.some_function() |
| logger.info("done with auxiliary_module.some_function()") |
| |
| Here is the auxiliary module:: |
| |
| import logging |
| |
| # create logger |
| module_logger = logging.getLogger("spam_application.auxiliary") |
| |
| class Auxiliary: |
| def __init__(self): |
| self.logger = logging.getLogger("spam_application.auxiliary.Auxiliary") |
| self.logger.info("creating an instance of Auxiliary") |
| def do_something(self): |
| self.logger.info("doing something") |
| a = 1 + 1 |
| self.logger.info("done doing something") |
| |
| def some_function(): |
| module_logger.info("received a call to \"some_function\"") |
| |
| The output looks like this:: |
| |
| 2005-03-23 23:47:11,663 - spam_application - INFO - |
| creating an instance of auxiliary_module.Auxiliary |
| 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO - |
| creating an instance of Auxiliary |
| 2005-03-23 23:47:11,665 - spam_application - INFO - |
| created an instance of auxiliary_module.Auxiliary |
| 2005-03-23 23:47:11,668 - spam_application - INFO - |
| calling auxiliary_module.Auxiliary.do_something |
| 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO - |
| doing something |
| 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO - |
| done doing something |
| 2005-03-23 23:47:11,670 - spam_application - INFO - |
| finished auxiliary_module.Auxiliary.do_something |
| 2005-03-23 23:47:11,671 - spam_application - INFO - |
| calling auxiliary_module.some_function() |
| 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO - |
| received a call to "some_function" |
| 2005-03-23 23:47:11,673 - spam_application - INFO - |
| done with auxiliary_module.some_function() |
| |