The logging Module

The stdlib logging package routes log records from loggers through handlers to outputs (console, files, syslog). Configure levels, formatters, and logger hierarchy once at startup - libraries log to named loggers without configuring handlers.

Recipe

import logging
 
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
log = logging.getLogger(__name__)
 
log.info("server starting")
log.warning("disk %s%% full", 92)

When to reach for this:

• Production services need leveled, filterable diagnostics
• Libraries emit logs without choosing output destination
• Multiple handlers (stderr + rotating file) per logger
• Structured fields later map from LogRecord attributes
• Replacing print debugging with operable trails

Working Example

import logging
from logging.handlers import RotatingFileHandler
 
def configure_logging() -> None:
    root = logging.getLogger()
    root.setLevel(logging.INFO)
    fmt = logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
 
    console = logging.StreamHandler()
    console.setFormatter(fmt)
    root.addHandler(console)
 
    file_handler = RotatingFileHandler("app.log", maxBytes=1_000_000, backupCount=3)
    file_handler.setFormatter(fmt)
    root.addHandler(file_handler)
 
configure_logging()
log = logging.getLogger("billing")
log.info("charge processed id=%s", "inv-1")
 
try:
    1 / 0
except ZeroDivisionError:
    log.exception("unexpected math failure")

What this demonstrates:

• basicConfig alternative: explicit handler attachment on root
• Named loggers inherit root level and handlers
• Lazy % formatting - arguments deferred if level filtered
• log.exception includes traceback when called inside except

Deep Dive

How It Works

• Loggers form hierarchy by dotted names (app.api, app.db)
• Records flow: logger -> filters -> handlers -> formatters -> IO
• Levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
• propagate controls bubbling to parent loggers
• Libraries call getLogger(__name__) only - no handler setup

Components

Gotchas

• basicConfig no-op if root configured - second call ignored. Fix: configure once in main or use dictConfig.
• Duplicate logs from propagate - child and root both have handlers. Fix: set logger.propagate = False or handlers only on root.
• f-strings in log calls - eager evaluation even when filtered. Fix: log.info("x=%s", x).
• print in libraries - bypasses levels and aggregation. Fix: logging only.
• DEBUG in production always on - volume and secret leakage. Fix: env-driven level, sample debug.

Alternatives

FAQs

Related

• Structured & Contextual Logging - JSON and correlation IDs
• Warnings & Deprecations - separate from logging
• Exceptions Basics - log and raise
• Errors & Logging Best Practices - policies

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.