14.5.2 Basic example

##
14.5.2 Basic example

Changed in version 2.4: formerly `basicConfig` did not take any keyword arguments.

The `logging` package provides a lot of flexibility, and its configuration can appear daunting. This section demonstrates that simple use of the logging package is possible.

The simplest example shows logging to the console:

    import logging

    logging.debug('A debug message')
    logging.info('Some information')
    logging.warning('A shot across the bows')

If you run the above script, you'll see this:

    WARNING:root:A shot across the bows

Because no particular logger was specified, the system used the root logger. The debug and info messages didn't appear because by default, the root logger is configured to only handle messages with a severity of WARNING or above. The message format is also a configuration default, as is the output destination of the messages - `sys.stderr`. The severity level, the message format and destination can be easily changed, as shown in the example below:

    import logging

    logging.basicConfig(level=logging.DEBUG,
                        format='%(asctime)s %(levelname)s %(message)s',
                        filename='/tmp/myapp.log',
                        filemode='w')
    logging.debug('A debug message')
    logging.info('Some information')
    logging.warning('A shot across the bows')

The `basicConfig()` method is used to change the configuration defaults, which results in output (written to `/tmp/myapp.log`) which should look something like the following:

    2004-07-02 13:00:08,743 DEBUG A debug message
    2004-07-02 13:00:08,743 INFO Some information
    2004-07-02 13:00:08,743 WARNING A shot across the bows

This time, all messages with a severity of DEBUG or above were handled, and the format of the messages was also changed, and output went to the specified file rather than the console.

Formatting uses standard Python string formatting - see section 3.6.2. The format string takes the following common specifiers. For a complete list of specifiers, consult the `Formatter` documentation.

Format | Description
--- | ---
`%(name)s` | Name of the logger (logging channel).
`%(levelname)s` | Text logging level for the message (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
`%(asctime)s` | Human-readable time when the `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).
`%(message)s` | The logged message.

To change the date/time format, you can pass an additional keyword parameter, datefmt, as in the following:

    import logging

    logging.basicConfig(level=logging.DEBUG,
                        format='%(asctime)s %(levelname)-8s %(message)s',
                        datefmt='%a, %d %b %Y %H:%M:%S',
                        filename='/temp/myapp.log',
                        filemode='w')
    logging.debug('A debug message')
    logging.info('Some information')
    logging.warning('A shot across the bows')

which would result in output like

    Fri, 02 Jul 2004 13:06:18 DEBUG    A debug message
    Fri, 02 Jul 2004 13:06:18 INFO     Some information
    Fri, 02 Jul 2004 13:06:18 WARNING  A shot across the bows

The date format string follows the requirements of `strftime()` - see the documentation for the `time` module.

If, instead of sending logging output to the console or a file, you'd rather use a file-like object which you have created separately, you can pass it to `basicConfig()` using the stream keyword argument. Note that if both stream and filename keyword arguments are passed, the stream argument is ignored.

Of course, you can put variable information in your output. To do this, simply have the message be a format string and pass in additional arguments containing the variable information, as in the following example:

    import logging

    logging.basicConfig(level=logging.DEBUG,
                        format='%(asctime)s %(levelname)-8s %(message)s',
                        datefmt='%a, %d %b %Y %H:%M:%S',
                        filename='/temp/myapp.log',
                        filemode='w')
    logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')

which would result in

    Wed, 21 Jul 2004 15:35:16 ERROR    Pack my box with 5 dozen liquor jugs