How to Properly Format the Python Logging Formatter in 2026

Raw log output is noise until it carries the context you need: when something happened, how serious it was, which component emitted it, and what state the system was in. In Python, all of that is decided by one small object — logging.Formatter — that turns each LogRecord into the line you actually read or ship to your log platform.

Getting the formatter right is the difference between logs you can trust during an incident and logs you scroll past. This guide explains how to properly format the Python logging formatter: the full constructor API, every useful LogRecord field, timestamp and timezone control, custom context, JSON output for production, subclassing, centralized configuration, and the mistakes that silently swallow your records. Everything here reflects the current standard library (Python 3.15, released in October 2026) and the versions of the most common companion libraries as of 2026.

Table of Contents#

What a Logging Formatter Actually Does#

Python's logging pipeline is short and worth keeping in your head:

Logger → (Filter) → Handler → Formatter → text written to a destination
  • The logger creates a LogRecord — a bag of metadata plus your message.
  • The handler decides where the record goes (console, file, socket, HTTP).
  • The formatter decides what the record looks like when it gets there.

Two consequences matter in practice:

  1. Formatters belong to handlers, not to loggers. handler.setFormatter(...) is the only way to attach one. This is also why a single application can print a short console format while writing a verbose format to a file — each handler carries its own formatter.
  2. A handler with no formatter falls back to the bare default. logging.Formatter() with no arguments uses the format string '%(message)s', i.e. your message alone, with no timestamp and no level.

The WARNING:root:disk space below 5% style output most people associate with "Python's default logging" is not that bare formatter. It comes from logging.basicConfig(), whose default format is the level name, logger name, and message joined with colons. Once you attach your own formatter, you own the layout completely.

What Formatter.format() does internally#

Before merging the record into your format string, Formatter.format() performs three preparation steps:

  1. Computes record.message as msg % args (the arguments from your logging call).
  2. Renders record.asctime via formatTime() if your format string references it.
  3. Formats any exception via formatException() and appends the traceback text to the output, then appends stack information via formatStack() if present.

That last point is essential: tracebacks are appended automatically. You do not put exception tuples in your format string.

The logging.Formatter Constructor Explained#

The full signature on current Python is:

logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)
ParameterPurposeNotes
fmtLayout of the whole log lineDefaults to '%(message)s'
datefmttime.strftime() string for asctimeDefaults to %Y-%m-%d %H:%M:%S plus milliseconds
style'%', '{', or '$' — how fmt is merged with record dataAdded in Python 3.2
validateMismatched fmt/style pairs raise ValueErrorAdded in Python 3.8; default True
defaultsMapping of fallback values for custom fieldsAdded in Python 3.10

The quickest way to format logs is still basicConfig(), which builds a handler and formatter for the root logger in one call:

import logging
 
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
    datefmt="%Y-%m-%dT%H:%M:%S",
)
logging.getLogger("billing").info("invoice %s emitted", 4711)
2026-10-12T09:15:04 | INFO     | billing | invoice 4711 emitted

Recent additions worth knowing:

  • force=True (Python 3.8) replaces any existing root handlers instead of doing nothing when logging is already configured.
  • encoding and errors (Python 3.9) control the FileHandler that filename= creates.
  • formatter= (Python 3.15) accepts a ready-made logging.Formatter instance — the clean way to use features like defaults= or a custom subclass from basicConfig().

For anything beyond a script, create the logger, handler, and formatter explicitly (or use dictConfig, covered below):

import logging
 
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
 
console = logging.StreamHandler()
console.setLevel(logging.INFO)
console.setFormatter(
    logging.Formatter("%(asctime)s | %(levelname)-8s | %(name)s | %(message)s")
)
logger.addHandler(console)

Naming your logger with __name__ keeps the %(name)s field meaningful: it shows the dotted module path (myapp.billing), which makes filtering and triage far easier than a pile of root entries.

LogRecord Attributes: Your Formatting Toolkit#

Format strings are assembled from LogRecord attributes. These are the placeholders documented for %-style formats (use {attrname} or ${attrname} in the other styles):

AttributePlaceholderDescription
asctime%(asctime)sHuman-readable creation time, e.g. 2003-01-23 00:29:50,411
created%(created)fCreation time as a POSIX timestamp
relativeCreated%(relativeCreated)dMilliseconds since the logging module was loaded
msecs%(msecs)dMillisecond portion of the creation time
levelname%(levelname)sLevel name (DEBUG, INFO, WARNING, …)
levelno%(levelno)sNumeric level (10, 20, 30, …)
name%(name)sLogger name, e.g. myapp.billing
message%(message)sThe rendered message (msg % args)
module%(module)sModule name (basename of the file)
filename%(filename)sFile name of the logging call
pathname%(pathname)sFull path of the logging call
funcName%(funcName)sFunction containing the logging call
lineno%(lineno)dLine number of the logging call
process%(process)dProcess ID
processName%(processName)sProcess name
thread%(thread)dThread ID
threadName%(threadName)sThread name
taskName%(taskName)sasyncio.Task name (added in Python 3.12)

A few attributes exist for the machinery's own use — args, msg, exc_info, exc_text, and stack_info. Their table entries say it outright: you shouldn't need to format them yourself. Exception text and stack traces are appended after the formatted line automatically.

Tips for choosing fields:

  • Console during development: asctime, levelname, name, message, plus filename:lineno when debugging.
  • Files and aggregation: add process/thread in multi-worker apps, taskName for asyncio services, and structured fields (see below) for request IDs.
  • Human-readable alignment: use width flags (next section) rather than tabs.

In {} style you also get full str.format() flags — the docs' own example is {msecs:03.0f}, which renders a millisecond value of 4 as 004.

Building a Readable Format String#

A good default for console output that stays scannable:

fmt = "%(asctime)s | %(levelname)-8s | %(name)-20s | %(message)s"
2026-10-12 09:15:04,082 | INFO     | myapp.billing        | invoice 4711 emitted
2026-10-12 09:15:04,095 | WARNING  | myapp.billing        | retry 1 for invoice 4712
2026-10-12 09:15:04,120 | ERROR    | myapp.payments       | gateway timeout after 30s

The -8s and -20s markers are printf-style width/alignment flags: pad the field to 8 or 20 characters and left-align it. That single trick makes triage faster because columns line up.

When a log entry needs its source location, extend the format rather than rewriting messages:

fmt = "%(asctime)s %(levelname)-8s %(name)s [%(filename)s:%(lineno)d %(funcName)s()] %(message)s"
2026-10-12 09:16:41,503 INFO     myapp.payments [gateway.py:88 charge()] retrying charge for order 9182

One format per handler#

Because formatters attach to handlers, give each destination the layout it deserves:

console = logging.StreamHandler()
console.setFormatter(logging.Formatter("%(levelname)-8s %(message)s"))
 
logfile = logging.FileHandler("app.log", encoding="utf-8")
logfile.setFormatter(
    logging.Formatter("%(asctime)s %(levelname)-8s %(name)s %(filename)s:%(lineno)d %(message)s")
)
 
logger.addHandler(console)
logger.addHandler(logfile)

Interpolate at the logging call, not before#

Call sites should pass arguments separately so formatting is deferred until (and unless) a record is actually emitted:

# Correct: lazy, safe, inspectable
logger.info("user %s signed in from %s", user_id, ip)
 
# Avoid: eager string building even when the level is disabled
logger.info(f"user {user_id} signed in from {ip}")

The record's message attribute is computed as msg % args, and no percent-formatting happens at all when you pass no arguments. Keep that contract: use %-style placeholders in the message plus positional arguments, and reserve the formatter's style for the overall line layout.

Format Styles: Percent, Braces, and Dollars#

Since Python 3.2, style selects how the format string is merged with record data:

# Default %-style
logging.Formatter("%(asctime)s %(levelname)-8s %(name)s: %(message)s")
 
# str.format() style — note width flags move after the colon
logging.Formatter("{asctime} {levelname:8s} {name}: {message}", style="{")
 
# string.Template style
logging.Formatter("$asctime ${levelname} $name: $message", style="$")

Two details keep people from tripping over this:

  1. style applies only to fmt — the layout of the whole line. Arguments inside a logging call (logger.error("bad %s", code)) remain %-style forever, for backward compatibility. Your line can use {} while messages use %, and vice versa.
  2. validate=True catches mismatches early. logging.Formatter('%(asctime)s - %(message)s', style='{') raises ValueError at construction time rather than producing garbage at 3 a.m.

Pick one style per codebase and stick to it. % is the most common and plays nicely with dictConfig strings copied from documentation; { is a better fit if your team prefers str.format() conventions; $ is rare but readable for people from shell backgrounds.

Dates and Timestamps That Correlate#

Timestamps are the backbone of incident response, and the defaults need conscious decisions.

Default behavior. Without datefmt, asctime looks like 2003-01-23 00:29:50,411 — time.strftime's %Y-%m-%d %H:%M:%S plus a comma and milliseconds. With datefmt, the string is passed straight to time.strftime, and millisecond suffixes are not appended.

Local time vs UTC. Rendering uses time.localtime by default. To log in UTC, set the converter attribute to time.gmtime — on an instance or, for app-wide effect, on the class:

import logging
import time
 
class UTCFormatter(logging.Formatter):
    converter = time.gmtime
 
utc = UTCFormatter(
    "%(asctime)s | %(levelname)-8s | %(message)s",
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
2026-10-12T13:15:04Z | INFO     | invoice 4711 emitted

This pattern is the standard-library recipe for UTC log times and pairs perfectly with ISO-8601 datefmt values (%Y-%m-%dT%H:%M:%SZ with the fixed Z, or %Y-%m-%dT%H:%M:%S%z for a numeric offset).

Milliseconds when you need them. The default time and millisecond suffixes are controlled by two class-level attributes introduced in Python 3.3: default_time_format (the strftime pattern) and default_msec_format (how milliseconds are appended, '%s,%03d' by default). Since Python 3.9, default_msec_format = None drops milliseconds entirely, and since Python 3.3 you can also override formatTime() for anything strftime cannot express (for example, ISO-8601 with fractional seconds).

class PreciseUTCFormatter(logging.Formatter):
    converter = time.gmtime
    default_msec_format = "%s.%03d"  # 2026-10-12 13:15:04.082

Consistency rule. Pick one timezone convention across every service (UTC is the sane default for anything that crosses regions) and one timestamp shape. Log pipelines that mix local times and formats break dashboards and delay root-cause analysis.

Adding Context Safely: extra, defaults, and LoggerAdapter#

Structured context — request IDs, tenant IDs, client IPs — is what modern observability runs on. The standard library gives you three mechanisms.

extra= at the call site#

Anything in extra is merged into the record's __dict__, so your format string can reference it by name:

fmt = "%(asctime)s %(clientip)-15s %(user)-8s %(message)s"
logging.basicConfig(format=fmt)
log = logging.getLogger("tcpserver")
 
log.warning(
    "protocol problem: %s",
    "connection reset",
    extra={"clientip": "192.168.0.1", "user": "fbloggs"},
)
2026-10-12 09:22:31,441 192.168.0.1     fbloggs  protocol problem: connection reset

Two sharp edges, straight from the documentation:

  • Keys in extra must not clash with built-in LogRecord attribute names.
  • If a custom key referenced by the format string is missing on a record, the formatting step raises and the message is not logged at all. Silent data loss.

defaults= on the formatter (Python 3.10+)#

Give every custom field a fallback so one forgotten extra cannot drop a record:

formatter = logging.Formatter(
    "%(asctime)s user=%(user)s ip=%(clientip)s %(levelname)s %(message)s",
    defaults={"user": "-", "clientip": "-"},
)

LoggerAdapter for repeated context#

For values that travel with a request or connection, wrap the logger once instead of threading extra= through every call:

class RequestAdapter(logging.LoggerAdapter):
    def process(self, msg, kwargs):
        kwargs.setdefault("extra", {}).update(self.extra)
        return msg, kwargs
 
log = RequestAdapter(logging.getLogger("myapp.web"), {"request_id": req_id})
log.info("cart updated")  # record already carries request_id

Since Python 3.13, LoggerAdapter also accepts merge_extra=True so per-call extra merges with the adapter's context instead of being overwritten. And since Python 3.2 you can push fields into every record with logging.setLogRecordFactory(), which is ideal for process-wide values like env or service.

One related knob: stacklevel= (Python 3.8) on a logging call skips wrapper frames so %(lineno)d and %(funcName)s point at your caller, not at the helper that did the logging.

Structured JSON Output for Production#

Plain text is for humans; log aggregation platforms want JSON objects. For production pipelines (Elasticsearch, OpenSearch, Datadog, Splunk, Loki), emit one JSON object per line.

The robust route: python-json-logger#

The de facto companion library is python-json-logger (4.x as of 2026, requires Python 3.10+). It provides logging.Formatter subclasses that encode records as JSON, so they drop into any handler or dictConfig setup:

pip install python-json-logger
import logging
from pythonjsonlogger.json import JsonFormatter
 
handler = logging.StreamHandler()
handler.setFormatter(
    JsonFormatter(
        "message,levelname,name,asctime",
        style=",",
        rename_fields={"levelname": "level", "name": "logger", "asctime": "timestamp"},
        defaults={"service": "billing-api"},
    )
)
logger = logging.getLogger("myapp.billing")
logger.addHandler(handler)
logger.setLevel(logging.INFO)
 
logger.info("invoice %s emitted", 4711, extra={"invoice_id": 4711, "amount_cents": 9900})
{"service": "billing-api", "message": "invoice 4711 emitted", "level": "INFO", "logger": "myapp.billing", "timestamp": "2026-10-12 09:15:04,082", "invoice_id": 4711, "amount_cents": 9900}

Capabilities worth knowing (all from its official quick start):

  • Field selection in several styles: the standard library styles %, {, $; a comma-separated style ("message,asctime,exc_info"); or a Python sequence (["message", "asctime", "exc_info"]). Omit the format entirely to serialize every non-reserved LogRecord attribute.
  • rename_fields maps attribute names to the keys your platform expects.
  • reserved_attrs controls which built-in attributes are excluded from output.
  • defaults / static_fields inject per-environment or constant fields on every record.
  • json_default customizes serialization of exotic objects.
  • Dict messages (logger.info({"my_data": 1, "message": "..."})) and extra fields both land in the JSON body.

A stdlib-only fallback#

If you cannot add a dependency, a short subclass is enough — note that you then handle exceptions yourself, because you are not delegating to super().format():

import json
import logging
import time
 
RESERVED = {
    "args", "asctime", "created", "exc_info", "exc_text", "filename",
    "funcName", "levelname", "levelno", "lineno", "message", "msecs",
    "module", "msg", "name", "pathname", "process", "processName",
    "relativeCreated", "stack_info", "taskName", "thread", "threadName",
}
 
class JsonLineFormatter(logging.Formatter):
    converter = time.gmtime  # UTC timestamps
 
    def format(self, record):
        payload = {
            "timestamp": self.formatTime(record, "%Y-%m-%dT%H:%M:%SZ"),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
        }
        for key, value in record.__dict__.items():
            if key not in RESERVED and not key.startswith("_"):
                payload[key] = value
        if record.exc_info:
            payload["exception"] = self.formatException(record.exc_info)
        return json.dumps(payload, default=str)

Companion libraries worth knowing#

  • colorlog (6.12 as of 2026, Python 3.6+) wraps logging.Formatter in a ColoredFormatter that paints output by level via a %(log_color)s placeholder and log_colors mapping. It honors NO_COLOR and FORCE_COLOR and disables colors automatically on non-TTY streams unless forced — useful for dev consoles, never for log files.
  • structlog takes a different route: a processor pipeline (add_log_level, TimeStamper, JSONRenderer, …) plus bound context (log.bind(request_id=...)) for services where request-scoped key/value data is the norm.

Subclassing Formatter for Full Control#

When the format string is not enough, subclass and override exactly one method.

Custom timestamps — override formatTime() (or set converter / default_time_format / default_msec_format):

class EpochFormatter(logging.Formatter):
    def formatTime(self, record, datefmt=None):
        return f"{record.created:.3f}"

Custom exception rendering — override formatException(). A single-line-per-event style for machine-parsed text files, based on the standard library's cookbook pattern:

class OneLineExceptionFormatter(logging.Formatter):
    def formatException(self, exc_info):
        return repr(super().formatException(exc_info))  # collapse the traceback
 
    def format(self, record):
        text = super().format(record)
        if record.exc_text:
            text = text.replace("\n", "") + "|"
        return text

One caveat straight from the reference docs: format() caches formatted exception text in record.exc_text, so if two custom formatters process the same record with different exception layouts, clear the cache (record.exc_text = None) between them. Also note formatStack() is the hook for stack_info=True output if you need to reshape it.

Configuring Formatters with dictConfig#

Hand-configuration scatters settings across modules. logging.config.dictConfig() (and its fileConfig sibling) centralizes them:

import logging
import logging.config
 
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "brief": {
            "format": "%(asctime)s | %(levelname)-8s | %(message)s",
            "datefmt": "%H:%M:%S",
        },
        "full": {
            "class": "logging.Formatter",
            "format": "%(asctime)s env=%(env)s | %(levelname)-8s | %(name)s | %(filename)s:%(lineno)d | %(message)s",
            "datefmt": "%Y-%m-%dT%H:%M:%S",
            "defaults": {"env": "prod"},
        },
        "json": {
            "()": "pythonjsonlogger.json.JsonFormatter",
            "format": "message,levelname,name,asctime",
            "style": ",",
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "brief",
            "stream": "ext://sys.stdout",
        },
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "level": "DEBUG",
            "formatter": "full",
            "filename": "app.log",
            "maxBytes": 10_000_000,
            "backupCount": 5,
        },
    },
    "root": {
        "level": "DEBUG",
        "handlers": ["console", "file"],
    },
}
 
logging.config.dictConfig(LOGGING)

What the formatters section accepts: format, datefmt, style, validate (Python 3.8+), and defaults (supported in dictConfig since Python 3.12 — older interpreters silently ignore the key, so pass defaults in code there). A class key (or the () factory syntax) instantiates a custom Formatter subclass — for example the UTCFormatter with converter = time.gmtime shown earlier. The ext:// prefix resolves dotted Python objects such as ext://sys.stdout. Configure the root logger under the top-level "root" key; reserve the loggers section for named loggers.

Why bother:

  • One file is the source of truth for every format string and handler.
  • Environments diverge by config file (or dict), not by code branches.
  • Custom formatter classes, third-party formatters (pythonjsonlogger.json.JsonFormatter, colorlog.ColoredFormatter), rotating file handlers, and filters all plug in declaratively.

Best Practices Checklist#

  1. Attach formatters to handlers and use one formatter per destination — brief for consoles, detailed for files, JSON for collectors.
  2. Always include asctime, levelname, name, and message. Add location fields in development, structured fields in production.
  3. Name loggers with __name__ so %(name)s reflects the module hierarchy.
  4. Set levels in two places deliberately: the logger's level decides what gets created; each handler's level decides what gets written. A DEBUG logger feeding an INFO handler is a normal way to keep files quiet and consoles chatty (or vice versa).
  5. Interpolate lazily at the call site (logger.info("user %s", uid)), never with pre-built f-strings.
  6. Log in UTC with ISO-8601 datefmt unless you have a strong reason not to.
  7. Reserve custom keys (extra, defaults) — never shadow LogRecord attribute names.
  8. Use defaults= for optional context so a missing field can't drop a record.
  9. Capture exceptions properly with logger.exception() (or exc_info=True); never format tracebacks by hand in the message string.
  10. Never log secrets — no passwords, tokens, raw card data, or unnecessary PII. Redact in a filter or processor if context values can carry them.
  11. Keep formats stable once log pipelines parse them; treat format strings as an interface.
  12. Configure in one place (dictConfig) for anything bigger than a script.

Common Formatting Mistakes and How to Fix Them#

1. Creating a formatter and forgetting to attach it. A formatter only takes effect after handler.setFormatter(...). Otherwise the handler's fallback formatter prints %(message)s only.

2. Typos in placeholder names. %(lvlname)s is not a LogRecord attribute. validate=True (the default) only checks that the format string matches its style; a misspelled field surfaces later at render time as ValueError: Formatting field not found in record. Keep the attribute table above within reach.

3. Referencing extra fields that aren't always present. If %(request_id)s is in the format but a record lacks request_id, the record is dropped by a formatting exception. Provide defaults={"request_id": "-"} or ensure a LoggerAdapter/record factory always supplies it.

4. Expecting %(exc_info)s to print a traceback. exc_info is an exception tuple meant for internal use; the traceback is appended to the formatted line automatically once exc_info=True or logger.exception() was used. Putting %(exc_info)s in the format string dumps a tuple repr.

5. "My formatter is ignored because of levels." Formatters don't filter. If the logger level is INFO, DEBUG records are discarded before any handler sees them. If no handler is configured at all, records at WARNING and above go to the lastResort stream handler on stderr with no timestamp.

6. Duplicate lines. If a record passes handlers on both a logger and its ancestors (via propagate), it is emitted more than once. Attach handlers at one level of the hierarchy — commonly just root — and leave propagate at its default of True.

7. Literal percent signs. When a logging call has arguments, msg % args runs first; an unescaped % in the message then causes a formatting error. Use %% for a literal percent, or pass no arguments.

8. Over-stuffed lines. PIDs, thread IDs, full pathnames, and function names on every console line bury the message. Rotate detail per handler instead.

9. Timezone confusion. Local timestamps in distributed systems look like ordering bugs when incidents span regions. Default to UTC (converter = time.gmtime).

10. Sensitive data in messages or context. Filters, custom format(), or third-party processors can redact — but the simplest control is not putting secrets into records.

FAQ#

What exactly is a "logging formatter"?#

A logging.Formatter instance — an object whose format(record) method turns a LogRecord into a string. The format string (fmt) is one of its constructor arguments. People say "formatter" for both; the distinction matters when attaching objects to handlers or overriding methods.

How do I change the timestamp format?#

Pass datefmt (a time.strftime pattern) to the formatter or basicConfig(datefmt=...). For UTC, set converter = time.gmtime. For shapes strftime can't express (epoch, ISO-8601 with milliseconds), override formatTime().

% or { format style — which should I use?#

Either is correct on modern Python; style has existed since 3.2 and mismatches are caught by validate. Choose based on team preference and what your config files already use, and keep it uniform across the project. Remember logging messages always use %-style arguments.

When should I use basicConfig() versus dictConfig()?#

basicConfig() is ideal for scripts, CLIs, and prototypes — one call, done. dictConfig() is the right tool for applications: multiple handlers, environment-specific formats, custom formatter classes, JSON output, rotation.

Should logs go to a file or to stdout?#

In containers and cloud environments, write to stdout (or stderr) and let the platform collect, rotate, and store logs. File output still makes sense for simple host deployments — pair it with rotation such as RotatingFileHandler.

How do I get JSON logs?#

Attach a JSON formatter to a handler: python-json-logger's JsonFormatter is the pragmatic choice, works with %/{/$/comma/sequence field selection, and integrates with dictConfig via its dotted class path. For heavily structured, context-bound logging, evaluate structlog alongside it.

Conclusion#

Formatting the Python logging formatter properly comes down to a handful of decisions made deliberately:

  • Treat logging.Formatter as a layout engine for LogRecord data: pick fmt, datefmt, and style knowingly, and lean on validate and defaults for safety.
  • Use the attribute toolkit fully — level, logger name, timestamp, and message at minimum; location fields in development; taskName, process/thread, and custom fields where they earn their space.
  • Align and pad fields so humans can scan; use UTC/ISO-8601 so machines can correlate.
  • Keep context safe with defaults, LoggerAdapter, or a record factory instead of fragile extra key assumptions.
  • Graduate to JSON (via python-json-logger or a small subclass) and to dictConfig once the codebase outgrows a single script.

Do that, and the formatter stops being an afterthought — it becomes the interface your team, your dashboards, and your incident response rely on.

References#