Aligning Log Timezones at Display Time, or Fixing Them at Write Time

Three rules I set on the write side

When I switched to changing what gets written, I allowed myself three rules. More than that and I would not have kept them.

1. Write in UTC, always with an explicit offset. 2026-09-01T03:12:00+00:00, so that whoever reads it later has nothing to guess. I accept a trailing Z on input, but I emit the explicit form.
2. Refuse naive values. The function above raises. When a source only ever returns naive timestamps, I write the assume for that source, so the assumption lives in code rather than in my memory.
3. Give each notion of "a day" its own name. My tables now carry report_day_admob, report_day_appstore, and run_day_jst as separate columns instead of one shared date.

The third rule did the most work. When the name is the same, the version of me reading it six weeks later treats them as the same thing. Splitting the column names forces the reconciliation code to state which day it is grouping by.

When I later folded Stripe payment logs into the same table, the same habit carried over. Payments already arrive in UTC, so instead of shifting anything I added one more explicitly named column.

A check that runs before reconciliation, not after

The migration window was the dangerous part. New lines carried offsets while older lines were still naive. Run an aggregation across that boundary and half your rows land nine hours away.

So I wrote something to run before the reconciliation starts.

import re
import sys
from collections import Counter
from pathlib import Path
 
TS = re.compile(r"\b(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(Z|[+-]\d{2}:?\d{2})?")
 
def scan(log_dir):
    kinds = Counter()
    samples = {}
    for path in Path(log_dir).rglob("*.log"):
        for lineno, line in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
            m = TS.search(line)
            if not m:
                continue
            offset = m.group(3)
            kind = "naive" if offset is None else ("utc" if offset in ("Z", "+00:00", "+0000") else offset)
            kinds[kind] += 1
            samples.setdefault(kind, f"{path.name}:{lineno}: {line[:80]}")
    return kinds, samples
 
if __name__ == "__main__":
    kinds, samples = scan(sys.argv[1])
    for kind, count in kinds.most_common():
        print(f"{kind:>10}  {count:>7}  {samples[kind]}")
    # Do not aggregate until the formats converge to one
    if len(kinds) > 1:
        print("\nMixed formats found. Normalise before aggregating.")
        sys.exit(1)

The last two lines are the whole point. A report that a human reads and judges is a report I skip on a busy morning. An exit code removes the judgement from the loop.

Since adding it, I have not once started an aggregation in the middle of a migration. It has not fired often, but every time it did, the formats really were mixed.

Where I landed

I now use both. Records are fixed to UTC with explicit offsets, and only the display is shifted to my local time.

Only the fourth row is a habit rather than a mechanism. When numbers disagree, the first thing I open is the raw log rather than the formatted view. Formatting makes things easier to read once you already have a question. It does not hand you the question.

Claude Code's timeZone setting lives above that fourth row. Now that shifting the display is supported properly, I have one fewer excuse for leaving the write side undefined.

Which side to start with

The right starting point depends on the shape of your sources. These are the rules of thumb I use.

• One source only? Start with display. If you write the log and you are the only reader, changing the write format is not worth the effort.
• Three or more sources? Start with the write side. Ads, store, and payments already put me past that line.
• Someone else reads the log? Start with the write side. Display settings differ per reader, so you cannot count on them agreeing.
• Cannot discard history? Start with the mixed-format check. Seeing the affected window matters more than deciding on a format.

Shifting is a decision you make for readers; fixing is a decision you make about your own responsibility as a writer. Get the order wrong and assumptions keep mixing behind a screen that reads beautifully. That is the one ordering I try not to break, even on a rushed day.

One thing to check tomorrow morning

Open a single log from your aggregation or monitoring and look at the end of a timestamp. If there is no offset there, that log currently carries an assumption that only the person who wrote it knows about.

Start there, and whether the check script is worth adding will answer itself. That is exactly where I restarted, staring at one line while trying to work out why two days at the end of the month refused to agree.