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.
import logging logging.basicConfig(level=logging.INFO) logging.info("server started")
Try it
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.
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
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. Passforce=Trueto 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()insideexceptblocks. It logs at ERROR level and includes the traceback. - Libraries should not configure logging. They create
getLogger(__name__), optionally add aNullHandler, and leave handlers and levels to the application. - Propagation: records go to the handlers of the logger and all its ancestors. Set
propagate = Falseto 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
QueueHandleror one writer per process when several processes log to one file. - Structured logs (JSON) need a custom
Formatteror a third-party package; the standard library formats text only. - Configuration from data:
logging.config.dictConfig()builds a full setup from a dictionary.