In the documentation of Goโs time package you will find the term โmonotonic clockโ roughly 30 times. However, you likely wonโt ever work with it directly. So, what is it for and why should you care?
In the previous article, we looked at how time.Time values represent โtime instantsโ on timelines using a time.Location reference.
When created using time.Now() a time.Time can also contain a different time representation: The monotonic clock reading.
Itโs represented on a timeline that is entirely seperate from to the ones provided by time.Location.
For example, a time.Time value in the time.UTC location with a monotonic clock reading would look like this when visualized:
time.Time value has two elements, a location and a monotonic clock reading.In this article we will take a look at:
- What it means for a clock to be monotonic.
- Why this is a desired property when โmeasuring timeโ.
- How this all works in the
timepackage. - And finally, what it means for your programs.
Letโs check
To begin, letโs take a look at a monotonic clock reading for ourselves.
Run the example below and take a look at the output.
As you can see, the time created via time.Now() contains an additional value at the end of its String() output. Something like:
This is the monotonic clock reading.
Itโs included in the output of the String() method for debugging purposes, but itโs not exported by the time.Time type.
To explain why itโs not exported, we need to zoom out a bit and look at monotonic clocks and โwall clocksโ.
What is a monotonic clock?
A clock is monotonic when it gives a guarantee about its readings: Every new reading is always greater than or equal to (>=) the previous reading.
In other words, it canโt be โturned backโ.
For example, suppose we have a clock that always returns integer values.
The following readings are monotonic:
Every reading is either:
- Equal to the previous reading.
- Greater than the previous reading.
These readings are not monotonic:
Inbetween the third (2) and fourth (1) reading the clock was โset backโ one unit, resulting in the fourth reading being lower than the one before.
Conceptually you might expect all clocks to be monotonic, but thatโs not the case.
What is a wall clock?
When you look at a clock on the wall and say โitโs 13:37โ that might seem like an easy thing to do.
However, if you dig a bit deeper it quickly turns rather complex: These wall clocks are generally coordinated using UTC and bound to a geographic location.
The coordination depends on human factors and is a social issue. I wonโt dig into the details (check out my guide for that), but the rules change all the time in ways that canโt be computed or predicted:
- Daylight saving time.
- Time zone changes.
- Leap seconds.
As a result wall clocks are turned back all the time.
They are not monotonic.
Telling time vs measuring time
The difference between wall clocks and monotonic clocks is sometimes described as:
- Wall clocks are for โtelling timeโ: assigning a useful meaning to a clock reading.
- Monotonic clocks are for โmeasuring timeโ: showing the passage of time between clock readings.
A wall clock can be used to tell time in a way that is coordinated with the rest of the world. For example, you can see itโs 13:37 in Iceland, and determine that corresponds to 12:37 in Cape Verde.
Wall clocks are inconvenient for measuring time. If you attempt to measure the interval between two clock readings, you need to compensate for any changes made to the clock inside that interval.
In contrast, to get the interval of two monotonic clock readings (from the same clock) you can subtract one from the other. There is no risk of the clock being set back.
However, monotonic clocks are not convenient for coordinating time with the rest of the world. The world sets back their clocks all the time.
System clock and monotonic clock
This is why most computer systems offer two clocks.
The system clock is a wall clock, itโs coordinated with the rest of the world and can be used to tell time.
The monotonic clock is a monotonic clock that is reset when the system restarts, itโs only guarantee is that it ticks forward (at a consistent pace). Clock readings are not coordinated, but can be used for measuring time while a program is running.
If you need to measure time across system restarts, you will need to fall back to using the system clock.
This is why the monotonic clock reading is unexported in Go's time.Time type. It doesn't have any meaning outside of the "current system boot" context.
Every system has a system clock, and most systems have a monotonic clock.
Reading clocks in Go: time.Now()
In Go the time.Time is used for both telling time and measuring time.
To achieve this, the time.Time type can store two elements: a wall time element and a monotonic element.
The wall time element is always present and works using the time.Location mechanism discussed earlier.
Before version 1.9 the time package only used the wall time, this lead to the Cloudflare leap second bug at the very end of 2016.
After that the monotonic clock was introduced in the Go time package.
Calling time.Now() will create a new time.Time value and set:
- The wall time element to the current system clock reading.
- The monotonic element to the current monotonic clock reading (if the system has one).
Letโs take a look at a very unsafe example that shows these elements in use.
In this example we create a mismatch between the two elements by (unsafely!) subtracting 60s from the monotonic element of the before value.
This 60s difference isnโt reflected in the times we see when displaying before and after as RFC3339 timestamps:
This is because the Format function only considers the wall time elements of the before and after values. Itโs a โtime tellingโ operation.
However, it is visible in the duration we compute using after.Sub(before):
This shows that the Sub method uses the monotonic elements in the time.Time values. In other words: itโs a โtime measuringโ operation.
Monotonic-first functions
The only way to create a time.Time value with a monotonic element is:
- Using the
time.Nowfunction (on a system with a monotonic clock). - Deriving a new
time.Timevalue by callingt.Add(u)on atvalue with a monotonic element.
The monotonic element is used by a limited set of methods:
t.After(u)t.Before(u)t.Equal(u)t.Compare(u)t.Sub(u)
These methods all use the monotonic element when itโs present in both t and u. It falls back to using the wall time element when itโs missing in t, u or both of them.
The t.Add(d) method adds the duration d to both the wall time and the monotonic element (if itโs present in t).
Wall time functions
All other functions only use or construct time.Time values with a wall time element. Values returned by time.Date, time.Parse or time.Unix* will never contain a monotonic element for example.
Noteably, some methods actively strip out the monotonic element:
t.AddDate(y, m, d)t.Round(d)t.Truncate(d)
Serializing functions
Since the monotonic element has no value outside of the โcurrent system bootโ context, itโs also never included when serializing a time.Time value.
Calling t.Format(layout), t.Marshal* or t.GobEncode() will not include the monotonic element.
This means that serializing and unserializing a time.Time value can be lossy. You will lose the monotonic element.
Practical tips
Practically this means that there are two kinds of time.Time values:
- Those with only a wall time element.
- Those with both a wall time and monotonic element.
As we saw, the behavior of some methods is different depending on the kind of value theyโre working with.
Test data
Usually you want test data to be consistent between test runs. To create consistent time.Time values itโs common to
use time.Date or time.Parse. This will only ever create values with a wall time element.
If in production these values are created using time.Now() you will end up with values containing both a wall time and a monotonic element.
This could result in different behavior between tests and production.
Depending on what youโre doing, this might (not) be an issue, but itโs good to be aware of it.
Remove monotonic element
The recommended way to remove the monotonic element of a time.Time value is using a t.Round(0) method call.
See this code snippet for an example.
Measure execution time
To measure execution time of an operation you can calculate the difference between two time.Time values created via time.Now().
See the example below.
Time not moving forward
The monotonic clock is guaranteed to not โmove backwardsโ, but it can return the same value multiple times.
In other words: Two calls to time.Now() might return the same time.Time value.
For example:
Assuming that only case 1 can happen will result in bugs.
Donโt assume UTC is monotonic
This article resulted in a question on Reddit that is worth repeating here:
Is UTC not monotonic? The examples given in the article are all geography based, which has its application but is often not relevant.
The UTC standard itself is monotonic. Time always moves forward.
However, applications donโt read UTC time directly.
They read UTC time from the system clock, which can potentially:
- Get out of sync and be adjusted by a network time protocol (NTP) service.
- Be adjusted by the OS.
- Be adjusted by the user.
In addition, systems handle UTC leap seconds in different ways. On some systems the same second gets repeated twice, making it look like the system clock was moved back a second.
Conclusion
In this article we took a look at the monotonic clock and its role in computing and more specifically itโs use in Go.
Key takeaways:
- A monotonic clock is a clock that canโt be โmoved backโ.
- Wall clocks are not monotonic clocks.
- Wall clocks are for telling time.
- Monotonic clocks are for measuring time.
- The
time.Timetype can contain both a wall element and a monotonic element. - Only
time.Now()andt.Add(d)can createtime.Timevalues with a monotonic element. - โMonotonic firstโ functions use the monotonic element when possible.
- There are other functions that ignore or actively remove the monotonic element.
I hope this article helps you write robust, time-aware applications. Keep these concepts in mind when you build your next project.
As always, if you have any questions or comments, feel free to reach out.
Happy coding!
Get my free newsletter periodically*
Used by 500+ developers to boost their Go skills.
*working on a big project as of 2025, will get back to posting on the regular schedule once time allows.
