Python Logging Explained: Levels, Handlers, Formatters and Mistakes to Avoid

A bug appears only in production, at 3 a.m., for one customer. The only evidence is whatever your application wrote down. Good logs turn that night into a ten-minute fix; print() statements scattered through the code usually do not.

We ran every example below with Python 3.13’s standard logging module. The outputs are from that run, with timestamps trimmed for readability.

Why not print()?

• Levels: logging lets you keep debug messages in the code and switch them off in production.
• Context: each record can include the time, module, level and line number automatically.
• Destinations: the same message can go to the console, a file and a log service at once.
• Control: libraries can log without forcing output on the applications that use them.

Log levels

A logger shows messages at its level and above. Out of the box, the root logger is set to WARNING, which surprises nearly every beginner:

logging.debug("debug hidden")
logging.info("info hidden")
logging.warning("warning shown")
# WARNING:root:warning shown

Only the warning appeared. Choose levels by who needs to act: if someone should be woken up, it is ERROR or CRITICAL; if it is useful only while investigating, it is DEBUG.

basicConfig and its quirk

logging.basicConfig() is the quickest way to set a level and format. But in our script, the earlier logging.warning() call had already configured the root logger behind the scenes, so this did nothing:

logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(message)s")
logging.debug("still hidden?")      # nothing printed

logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(message)s", force=True)
logging.debug("visible with force=True")
# DEBUG visible with force=True

basicConfig only acts if the root logger has no handlers yet. Calling any module-level function such as logging.warning() first, or importing a library that configures logging, means your settings are silently ignored. Call it once, at the very start of your program, or pass force=True (Python 3.8+) to replace the existing setup.

Named loggers

# in shop/orders.py
log = logging.getLogger(__name__)    # name: "shop.orders"

Loggers form a tree based on dotted names. shop.orders and shop.payments are children of shop, which is a child of the root logger. By default, a child passes its records up to its parents, which is called propagation. That is why configuring only the root logger at startup is enough for every module: their records all flow up to the root’s handlers. In our test, a record from shop.payments was printed by the root’s handler as ROOT shop.payments: payment ok.

Named loggers also let you tune noisy parts separately, for example logging.getLogger("urllib3").setLevel(logging.WARNING) to quieten a chatty library.

Handlers and formatters

A handler decides where records go; a formatter decides how they look.

h = logging.StreamHandler()
h.setFormatter(logging.Formatter(
    "%(asctime)s %(name)s %(levelname)s %(message)s",
    datefmt="%Y-%m-%dT%H:%M:%S"))

log = logging.getLogger("shop.orders")
log.addHandler(h)
log.setLevel(logging.INFO)

log.debug("not shown")
log.info("order %s created for %s", 101, "Asha")
log.warning("stock low: %d left", 2)

# 2026-11-08T17:40:18 shop.orders INFO order 101 created for Asha
# 2026-11-08T17:40:18 shop.orders WARNING stock low: 2 left

Common handlers include StreamHandler for the console, FileHandler, RotatingFileHandler and TimedRotatingFileHandler for files that should not grow forever, and SysLogHandler. Each handler can have its own level, so you can write everything to a file but only warnings to the console.

Logging exceptions

try:
    1 / 0
except ZeroDivisionError:
    log.exception("failed to compute tax")

# shop.orders ERROR failed to compute tax
# Traceback (most recent call last):
#   File "...logdemo.py", line 23, in <module>
#     1 / 0
# ZeroDivisionError: division by zero

log.exception() logs at ERROR level and attaches the full traceback automatically. Use it inside except blocks instead of log.error(str(e)), which throws away the most useful part. Our guide to Python exception handling shows where to catch and log errors.

Lazy formatting: why %s beats f-strings here

We logged an object whose __str__ counts how often it is called, at DEBUG level, on a logger set to WARNING:

quiet.debug("value %s", e)
print(Expensive.calls)    # 0

quiet.debug(f"value {e}")
print(Expensive.calls)    # 1

With the %s style, logging never built the message, because DEBUG was disabled. With the f-string, Python built the text before logging even saw it, and then threw it away. In a hot loop, or with expensive objects, that waste adds up. As our f-strings guide notes, logging is one of the few places where the older style is the better choice. Some linters, such as Ruff and Pylint, can flag f-strings in logging calls.

Duplicate log lines

The most common logging bug is every message appearing two or three times. We reproduced both causes:

for _ in range(3):
    dup.addHandler(logging.StreamHandler())
dup.warning("hello")
# lines written: 3

Adding a handler inside a function that runs more than once, such as a request handler or a test setup, stacks up handlers. The second cause is propagation: when we added a handler to shop.payments while the root logger also had one, the message twice? was written by both. Fix it by configuring handlers once, at startup, usually only on the root logger. If a child really needs its own handler, set propagate = False on it.

Structured JSON logs

Plain text is easy to read but hard to search across thousands of lines. Log platforms prefer one JSON object per line. A small custom formatter is enough to start:

class JsonFormatter(logging.Formatter):
    def format(self, r):
        d = {"level": r.levelname, "logger": r.name, "msg": r.getMessage()}
        d.update(getattr(r, "ctx", {}))
        return json.dumps(d)

jl.info("request done", extra={"ctx": {"path": "/orders", "status": 200, "ms": 42}})
# {"level": "INFO", "logger": "api", "msg": "request done", "path": "/orders", "status": 200, "ms": 42}

Fields like status and ms can now be filtered and charted directly. Libraries such as structlog and python-json-logger provide fuller versions. Structured logs are one of the three pillars discussed in our guide to monitoring vs observability.

Configuring an application

For anything beyond a script, keep logging setup in one place, using logging.config.dictConfig(). It accepts a dictionary, which you can load from a YAML or JSON file, describing formatters, handlers and logger levels. Set levels from an environment variable, such as LOG_LEVEL=DEBUG locally and INFO in production, so you can turn on detail without a code change. We did not run a full dictConfig setup for this article.

Best practices

• Never log secrets such as passwords, tokens, card numbers or full personal data. Redact before logging.
• Log events, not noise. One clear line per meaningful event beats ten vague ones.
• Include identifiers such as order ID, user ID or request ID, so related lines can be found together.
• Use UTC timestamps in ISO format in production, so logs from different servers line up.
• Rotate or ship logs so files do not fill the disk.
• Test important logs. pytest’s caplog fixture captures records, as shown in our pytest fixtures guide.

Testing your logs with caplog

Some log lines matter enough to test, such as the warning that an alert depends on. pytest’s built-in caplog fixture captures records during a test:

log = logging.getLogger("shop.orders")

def place_order(qty):
    if qty <= 0:
        log.warning("rejected order with qty=%s", qty)
        return False
    log.info("order placed qty=%s", qty)
    return True

def test_logs_warning(caplog):
    with caplog.at_level(logging.INFO, logger="shop.orders"):
        assert place_order(0) is False
    assert caplog.records[0].levelname == "WARNING"
    assert "qty=0" in caplog.text

# captured: [('WARNING', 'rejected order with qty=0')]

The test passed. Assert on the level and the important values rather than the full sentence, so rewording a message does not break the test. caplog.at_level() temporarily lowers the level for the duration of the block, which also makes DEBUG messages testable.

Final thoughts

Python’s logging module is powerful but has a few sharp edges: the WARNING default, basicConfig’s silent no-op, duplicate handlers and propagation. Use getLogger(__name__) in every module, configure handlers once at startup, use %s-style arguments and log.exception(), and move to JSON logs when you start searching them at scale.

Frequently asked questions

Keep learning