Formatting Timestamps and Timezones in Python Logs

Python's default log timestamp is local time, with no timezone indicator, at a precision of milliseconds separated by a comma. Each of those properties causes a distinct problem once logs from more than one host are in the same store: events that cannot be merged across regions, an hour each year when timestamps are ambiguous, and parsers that reject the format outright. This page covers the fix — UTC, RFC 3339, enough precision to order events — and the pipeline setting that decides whether the application's timestamp is used at all. It is a task article under formatter configuration, part of the Python logging fundamentals and structured data section.

Prerequisites

The standard library is sufficient; a JSON formatter makes the timestamp one field among others.

pip install "python-json-logger>=2.0.7,<4.0.0"

Implementation

Step 1 — Convert to UTC in the formatter. A formatter's converter attribute decides how record.created becomes a time tuple, and it defaults to local time. Setting it to time.gmtime makes every timestamp UTC regardless of the host's configuration, which matters because container images, developer machines and cloud hosts are configured inconsistently and nobody should have to know which one produced a record.

import logging
import time

formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
formatter.converter = time.gmtime               # 1. UTC, whatever the host says

Step 2 — Emit RFC 3339 with an explicit marker. The default format has no timezone indicator at all, and it separates milliseconds with a comma. RFC 3339 — the profile of ISO 8601 used by nearly every log store — puts a T between date and time, a dot before fractional seconds, and a Z or numeric offset at the end. Overriding formatTime produces exactly that.

from datetime import datetime, timezone

class Rfc3339Formatter(logging.Formatter):
    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
        # 2. From the record's own creation time, to the microsecond, in UTC.
        dt = datetime.fromtimestamp(record.created, tz=timezone.utc)
        return dt.isoformat(timespec="microseconds").replace("+00:00", "Z")

Expected Output: an unambiguous, sortable, parseable timestamp.

2026-09-18T14:02:11.408213Z INFO orders order accepted

Step 3 — Keep enough precision to order events. At second precision, every record within the same second is tied, and the order an investigation needs — did the retry happen before or after the timeout — is lost. Millisecond precision is the minimum; microseconds cost nothing in a JSON field and resolve the cases where several events happen within one millisecond on a busy thread.

Step 4 — Take the time from the record. record.created is set when the log call is made. A formatter that calls datetime.now() instead stamps the record with the time it was formatted, which under a queue handler happens later, on the listener thread, possibly after a backlog. The difference is usually small and occasionally several seconds, and it silently reorders events that were logged close together on different threads.

# wrong under a QueueHandler: the time of formatting, not of the event
dt = datetime.now(timezone.utc)

# right: the time the log call was made
dt = datetime.fromtimestamp(record.created, tz=timezone.utc)

Step 5 — Put the timestamp in a named field in structured output. In JSON logs the timestamp should be a dedicated field with a conventional name, so the collector can be told which field is the event time. A timestamp embedded in a message string is invisible to the pipeline.

from pythonjsonlogger import jsonlogger

class UtcJsonFormatter(jsonlogger.JsonFormatter):
    def add_fields(self, target, record, message_dict):
        super().add_fields(target, record, message_dict)
        target["@timestamp"] = datetime.fromtimestamp(
            record.created, tz=timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
        target.pop("asctime", None)

Step 6 — Tell the pipeline to use it. A log shipper that does not know which field is the event time uses the time it read the record, which is later — sometimes much later under backpressure. Configuring the shipper to parse the application's field as the event time makes the store's ordering reflect when things happened rather than when they were collected. The shipper side is covered in shipping Python logs with Fluent Bit.

Clocks, and what a timestamp can tell you

Correct formatting makes timestamps unambiguous. It does not make them accurate, and it is worth knowing how far they can be trusted.

Clocks drift between hosts. Each host's clock is kept in sync by a time protocol, typically to within a few milliseconds and occasionally much worse after a host's clock has been stepped. Two records from different hosts with timestamps a millisecond apart may in reality have happened in either order. For ordering events across services, a trace's parent-child relationships are authoritative where timestamps are merely suggestive — which is one of the strongest reasons to add trace identifiers to log records.

Wall clocks can go backwards. A clock correction can step the system time backwards, producing records whose timestamps are earlier than records logged before them on the same host. record.created comes from the wall clock, so this affects logs directly. Durations should never be computed by subtracting two log timestamps; they belong in a field computed with a monotonic clock at the point of measurement.

Precision is not accuracy. Microsecond precision records the value the clock returned to the microsecond. The clock itself may be several milliseconds off true time, and the formatting says nothing about that. Precision is valuable for ordering records from one process, where a single clock is shared; across processes its extra digits are mostly noise.

The practical position is: format timestamps in UTC with high precision so that nothing is lost at the formatting stage, use them for ordering within a process and approximate ordering across processes, and rely on traces for causality and monotonic measurements for durations.

Timestamps inside the record, not only on it

The record's own timestamp says when the log call was made. Many records also carry times inside their fields — when an order was placed, when a token expires, when a retry is scheduled — and those deserve the same treatment for the same reasons.

A field such as expires_at serialised from a naive datetime becomes a string with no timezone, and any consumer comparing it with the record's UTC timestamp is comparing two different clocks without knowing it. The common failure is a formatter that handles record.created correctly while json.dumps(..., default=str) turns every other datetime into local, offset-less text.

The fix is a single rule applied in the formatter: any datetime value in any field is converted to UTC and rendered in the same RFC 3339 form as the record's timestamp. Naive datetimes — those without timezone information — are the dangerous ones, because there is no way to know what they meant; treating them as an error during testing, and fixing them at the source to be timezone-aware, is better than guessing in the formatter.

Durations deserve their own field type as well. A duration logged as a timedelta string — "0:00:00.041200" — is human-readable and hard to query. Logging it as a number of milliseconds in a field named with its unit, such as duration_ms, makes it filterable, aggregatable and unambiguous, and it avoids the temptation to compute durations from two log timestamps, which the clocks discussion above explains is unreliable.

Configuration options

Verification

Confirm the timestamp parses as UTC and orders correctly relative to a known sequence.

import logging, json, io
from datetime import datetime

stream = io.StringIO()
h = logging.StreamHandler(stream); h.setFormatter(UtcJsonFormatter("%(message)s"))
log = logging.getLogger("ts"); log.handlers = [h]; log.propagate = False
for i in range(3):
    log.warning("event %d", i)

stamps = [json.loads(l)["@timestamp"] for l in stream.getvalue().splitlines()]
parsed = [datetime.fromisoformat(s.replace("Z", "+00:00")) for s in stamps]
assert all(p.utcoffset().total_seconds() == 0 for p in parsed)
assert parsed == sorted(parsed)
print(stamps[0])

Expected Output:

2026-09-18T14:02:11.408213Z

Common mistakes

The default local-time format. Error signature: records from different regions sorting hours apart. Root cause: local time with no offset. Remediation: UTC via the formatter's converter.

A comma before the milliseconds. Error signature: a shipper failing to parse the timestamp and falling back to arrival time. Root cause: the default format's separator. Remediation: RFC 3339 with a dot.

Stamping at format time. Error signature: records from a busy period slightly reordered under a queue handler. Root cause: now() called in the formatter. Remediation: use record.created.

Second precision. Error signature: ties that hide the order of a retry and a timeout. Root cause: a format without fractional seconds. Remediation: milliseconds at least.

The store using arrival time. Error signature: events appearing late and out of order after collector backlogs. Root cause: the shipper not configured with the event time field. Remediation: parse the application's timestamp as the event time.

Frequently Asked Questions