Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The logging module

Reference for Python's logging module: levels, getLogger, basicConfig, handlers, formatters, exception logging, propagation and why logging beats print.

The logging module records what your program is doing, with a severity level and an optional destination (console, file, network). Unlike print(), you can turn detail up or down, route messages to several places and add timestamps and module names without touching the code that logs.

The model has four parts. A logger is what your code calls. Each message has a level. Handlers send records somewhere, and formatters decide how a record looks. Loggers have dotted names (app.db) that form a tree: a record travels up to the parent loggers' handlers.

Python
import logging

logging.basicConfig(level=logging.INFO)
logging.info("server started")

Try it

Python Levels, format and a named logger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Handlers, levels and filtering

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
logger = logging.getLogger(name)
logger.debug(msg, *args, **kwargs)      # also info, warning, error, critical, exception
logging.basicConfig(**kwargs)
logging.Formatter(fmt=None, datefmt=None, style='%')
Name Description
name Dotted logger name. Use __name__ in modules. getLogger() with no name returns the root logger.
msg, *args Message with %s-style placeholders; arguments are filled in only if the record is actually emitted.
exc_info=True Adds the current exception's traceback (done automatically by exception()).
extra={...} Adds custom fields to the record for use in formats.
stacklevel Reports a caller higher up the stack as the source of the message.

Levels, lowest to highest: DEBUG (10), INFO (20), WARNING (30, the default threshold), ERROR (40), CRITICAL (50). Common basicConfig() options: level, format, datefmt, filename, filemode, stream, handlers, force.

Useful handlers: StreamHandler, FileHandler, RotatingFileHandler and TimedRotatingFileHandler (in logging.handlers), NullHandler. Common format fields: %(asctime)s, %(levelname)s, %(name)s, %(message)s, %(filename)s, %(lineno)d, %(funcName)s.

Return value: the logging methods return None; getLogger() returns the same object every time for one name.

Usage notes

  • Default behavior: with no configuration, only WARNING and above appear, as bare messages on standard error.
  • basicConfig() does nothing the second time if the root logger already has handlers. Pass force=True to replace them.
  • Pass arguments, do not format: log.info("user %s", name) is cheaper than an f-string when the level is disabled, and keeps similar messages groupable.
  • Use log.exception() inside except blocks. It logs at ERROR level and includes the traceback.
  • Libraries should not configure logging. They create getLogger(__name__), optionally add a NullHandler, and leave handlers and levels to the application.
  • Propagation: records go to the handlers of the logger and all its ancestors. Set propagate = False to stop that, or you will see duplicate lines.
  • Levels filter twice: a record must pass the logger's level, then each handler's level.
  • Never log secrets such as passwords, tokens or full card numbers.
  • Thread-safe, but not process-safe for file output; use a QueueHandler or one writer per process when several processes log to one file.
  • Structured logs (JSON) need a custom Formatter or a third-party package; the standard library formats text only.
  • Configuration from data: logging.config.dictConfig() builds a full setup from a dictionary.