Seconds or milliseconds
Unix time counts from 1 January 1970 UTC. The ambiguity that causes most bugs is the unit: Unix tooling and most APIs count seconds, while JavaScript counts milliseconds. A ten-digit number is seconds, a thirteen-digit number is milliseconds.
Getting this wrong produces dates that are obviously absurd - a timestamp in seconds read as milliseconds lands in January 1970, and the reverse lands tens of thousands of years in the future. If a date in your logs looks impossible, the unit is almost always the reason.
UTC, local time, and why logs use UTC
A Unix timestamp has no timezone. It is an absolute instant, and the timezone only appears when it is rendered for a human. This is why storing timestamps rather than formatted dates avoids an entire category of bug: no daylight-saving transition can corrupt a number.
Both UTC and your local rendering are shown here because debugging usually needs both. Your logs are almost certainly UTC, while the customer describing the problem is telling you their local time - and reconciling the two by hand is where mistakes creep in.
ISO 8601 as the interchange format
When a timestamp has to be readable as well as machine-parseable, ISO 8601 is the format to use. It sorts correctly as a plain string, it is unambiguous about timezone when the offset is included, and every language parses it without a custom format string. Prefer it over any locale-specific format the moment data crosses a system boundary.
Frequently asked questions
- Is my timestamp in seconds or milliseconds?
- Count the digits. Ten digits is seconds, thirteen is milliseconds. Current timestamps in seconds begin with 17; in milliseconds they are a thousand times larger.
- What is the Unix epoch?
- Midnight on 1 January 1970 UTC, the zero point Unix timestamps count from. Negative timestamps represent times before it.
- Do Unix timestamps have a timezone?
- No. A timestamp is an absolute instant. Timezone only applies when it is rendered as a date, which is why storing timestamps avoids daylight-saving bugs entirely.
- What is the year 2038 problem?
- Systems storing Unix time in a signed 32-bit integer overflow in January 2038. Modern platforms use 64-bit values and are unaffected, but old embedded systems and legacy databases may not be.