Time & Timezones Demystified
You’ve shipped a time bug. You just don’t know it yet.
The Day Time Broke
You’ve shipped a time bug. You just don’t know it yet.
The leap second that took down half the internet
On June 30, 2012, at 23:59:60 UTC, the world’s clocks gained an extra second. A bug in the Linux kernel’s leap-second handling caused a flood of futex wakeups across thousands of servers. CPU usage on affected machines pinned at 100%.
Reddit went dark. LinkedIn followed. Mozilla’s build infrastructure stalled. Yelp and FourSquare had outages. Qantas had to switch to manual check-in for hours because their reservation system, Amadeus Altea, was paralyzed by the same bug.
The root cause wasn’t the leap second itself. It was that every team building those systems had assumed every minute has 60 seconds. Twice a year, twenty-three of those minutes were wrong. Once in five years, a minute had 61.
Why time is harder than it looks
Universal
Every program touches time. Logs, sessions, billing, scheduling, cache, retries, JWTs, alerts — all of it.
Invisible
Time bugs hide for months. Code that “works” in dev and staging breaks in production exactly twice a year, in specific zones, in specific hours.
Expensive
When time bugs do show up, they show up as duplicate charges, missed alerts, lost data, or paged engineers. Always at 2 AM.
What you’ll learn
Foundations
The distinction between an instant and a wall-clock reading. What UTC actually is. Why a timezone isn’t an offset.
Hazards
DST gaps and folds. Leap years and leap seconds. Calendars that don’t agree. The IANA tz database that updates while you sleep.
Shipping it
How to store time. How to format it. How to schedule recurring events without double-firing. Why the client’s clock is a liar.
Use the → key or click Instant vs Civil in the sidebar to begin.