Next

The logging functions are named after the level or severity of the events they are used to track. The standard levels and their applicability are described below (in increasing order of severity):

The default level is WARNING, which means that only events of this level and above will be tracked, unless the logging package is configured to do otherwise.

Events that are tracked can be handled in different ways. The simplest way of handling tracked events is to print them to the console. Another common way is to write them to a disk file.

import logging
logging.warning("Watch out!")  # will print a message to the console
logging.info("I told you so")  # will not print anything

If you type these lines into a script and run it, you’ll see:

WARNING:root:Watch out!

printed out on the console. The INFO message doesn’t appear because the default level is WARNING. The printed message includes the indication of the level and the description of the event provided in the logging call, i.e. ‘Watch out!’. Don’t worry about the ‘root’ part for now: it will be explained later. The actual output can be formatted quite flexibly if you need that; formatting options will also be explained later.

A very common situation is that of recording logging events in a file, so let’s look at that next. Be sure to try the following in a newly-started Python interpreter, and don’t just continue from the session described above:

import logging
logging.basicConfig(filename="example.log",level=logging.DEBUG)
logging.debug("This message should go to the log file")
logging.info("So should this")
logging.warning("And this, too")

And now if we open the file and look at what we have, we should find the log messages:

DEBUG:root:This message should go to the log file
INFO:root:So should this
WARNING:root:And this, too

This example also shows how you can set the logging level which acts as the threshold for tracking. In this case, because we set the threshold to DEBUG, all of the messages were printed.

To log variable data, use a format string for the event description message and append the variable data as arguments. For example:

import logging
logging.warning("%s before you %s", "Look", "leap!")

will display:

WARNING:root:Look before you leap!

As you can see, merging of variable data into the event description message uses the old, %-style of string formatting. This is for backwards compatibility: the logging package pre-dates newer formatting options such as str.format() and string.Template. These newer formatting options are supported, but exploring them is outside the scope of this tutorial: see Using particular formatting styles throughout your application for more information.

To change the format which is used to display messages, you need to specify the format you want to use:

import logging
logging.basicConfig(format="%(levelname)s:%(message)s", level=logging.DEBUG)
logging.debug("This message should appear on the console")
logging.info("So should this")
logging.warning("And this, too")

which would print:

DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too

Notice that the ‘root’ which appeared in earlier examples has disappeared. For a full set of things that can appear in format strings, you can refer to the documentation for LogRecord attributes, but for simple usage, you just need the levelname (severity), message (event description, including variable data) and perhaps to display when the event occurred. This is described in the next section.

To display the date and time of an event, you would place ‘%(asctime)s’ in your format string:

import logging
logging.basicConfig(format="%(asctime)s %(message)s")
logging.warning("is when this event was logged.")

which should print something like this:

2010-12-12 11:41:42,612 is when this event was logged.

The default format for date/time display (shown above) is ISO8601. If you need more control over the formatting of the date/time, provide a datefmt argument to basicConfig, as in this example:

import logging
logging.basicConfig(format="%(asctime)s %(message)s", datefmt="%m/%d/%Y %I:%M:%S %p")
logging.warning("is when this event was logged.")

which would display something like this:

12/12/2010 11:46:36 AM is when this event was logged.

The format of the datefmt argument is the same as supported by time.strftime().