System.system_time vs System.os_time

Does anybody know the practical implications of using System.os_time/0 vs System.system_time/0?

I notice DateTime.utc_now/0 uses os_time/0.

There is some mention of the differences in the docs for system_time/0:

It is the VM view of the os_time/0. They may not match in
case of time warps although the VM works towards aligning
them. This time is not monotonic.

Likewise, the Erlang docs also discuss some implications:

OS System Time

The operating systems view of POSIX time. To retrieve it, call os:system_time(). This may or may not be an accurate view of POSIX time. This time may typically be adjusted both backwards and forwards without limitation. That is, time warps may be observed.

Erlang System Time

The Erlang runtime systems view of POSIX time. To retrieve it, call erlang:system_time().

This time may or may not be an accurate view of POSIX time, and may or may not align with OS system time. The runtime system works towards aligning the two system times. Depending on the time warp mode used, this can be achieved by letting Erlang system time perform a time warp.

However, besides the talk of time warps and what exactly each of the functions return, there is never really any advice about when you would want one or the other.


I happened across this article recently - the linked section digs into which flavors of time you might want for various applications:


Thanks for the link, super interesting. It covers the difference between monotonic and wall time well, but it doesn’t really cover OS Time vs System Time. The erlang docs seem to suggest that for getting the wall time, System Time should be the default, however, DateTime in Elixir uses OS Time. I wonder if there’s a reason for that?

1 Like

I would say OS time is correct. For an embedded device Or desktop application, if the os time changes, then it should be immediately reflected in the app. The same for log timestamps and so on. For servers I may not Matter anyway as they are usually in UTC and do not observe jumps.


That seems to make sense, but if that’s the case then what is the point of system time and time warps existing at all?

Quoting the erlang docs again:

The number of problems that arise when you always expect the wall clock time on the system to be correct can be immense. Erlang therefore introduced the “corrected estimate of time”, or the “time correction”, many years ago.


As we align Erlang system time with OS system time by changing the time offset, we can enable a time correction that tries to adjust the frequency of the Erlang monotonic clock to be as correct as possible. This makes time measurements using Erlang monotonic time more accurate and precise.

This is saying that there are problems being solved and accuracy and precision benefits to Erlang monotonic time, but it does not mention why Erlang system time (based on Erlang monotonic time) would be preferable to OS system time.

learn you some Erlang also discusses this, but again does not make a recommendation between System and OS time.


As most servers use Network Time Protocol (NTP) the time may jump as time drifts and it’s synchronized with the external clock. Have seen this happen in production and the results weren’t pretty. Scanner imports were rejected because the servers’ clock jumped backward, even when it was a small amount.

Those are the cases where system_time seems to be designed for, where ‘system’ is ‘Erlang’. You can tune how it behaves when such jump (or drift) happens. For instance: only allow ‘time’ to go forward, no jumps (using correction).

As a result the time you get might not immediately be the time you expect, but it’s more robust and predictable from a systems’ perspective.


os_time for user observable time as it matches expectation and wall clock. Examples:

  • the new log entry has a timestamp matching the clock on the wall
  • the clock shown on the screen matches the clock on the wall

system_time for internal time(rs) & time measuring as external interference with the clock is dampened and the clock is more predictable for processes. Examples:

  • order events by timestamp will always match order by incremental id
  • processes expected to run on a strict interval will not alert due to a time jump

ps. I am not an expert
pps. There is no better way then getting the answer from an expert than posting a wrong answer. So when it’s wrong we will find out soon.


It seems like both of these cases could be handled by using monotonic time. Do you see a use for Erlang system time specifically over monotonic time here?

Primary source of document in Erlang “system time”: Time and Time Correction in Erlang

If you’re depending on precise time continuity and non-repudiation of time (i.e., monotonicity of time) within Erlang VM, use erlang:system_time/0-1.

Yes I have quoted that document multiple times above :slight_smile:

The question is really:

When should we prefer to use the Erlang system time over OS time, as opposed to simply monotonic time, either as erlang:monotonic_time or as System.monotonic_time/0?

Erlang monotonic time increases since some unspecified point in time
Even Erlang system time is based on Erlang monotonic time. By adding current Erlang monotonic time with current time offset, you get current Erlang system time.
To retrieve the current time offset, callerlang:time_offset/0.

When you also want to use the time other than ‘time elapsed’ (eg. print or store start- and stop time of measurement) you better use system time as monotonic time has no reference to a ‘clock on the wall’ at all.