APIs that accept time ranges support three parameters:
- Start time (
- End time (
- Time zone (
Time zone can be any valid time zone id string.
Named times are references that will get resolved to a timestamp when a query is
executed. For example, with graphs it is common to set the end time to
||User specified start time. Can only be used as part of the end parameter.|
||User specified end time. Can only be used as part of the start parameter.|
||January 1, 1970 UTC.|
Explicit timestamps can use the following formats:
|%Y-%m-%d||Date using the timezone for the query. The time will be 00:00.|
|%Y-%m-%dT%H:%M||Date time using the timezone for the query. The seconds will be 00.|
|%Y-%m-%dT%H:%M:%S||Date time using the timezone for the query.|
|%s||Seconds since January 1, 1970 UTC.|
|%s (ms)||Milliseconds since January 1, 1970 UTC.|
For times since the epoch both seconds and milliseconds are supported because both are in common use and it helps to avoid confusion when copy and pasting from another source. Values less than or equal 2,147,483,648 (231) will be treated as a timestamp in seconds. Values above that will be treated as a timestamp in milliseconds. So times from the epoch to 1970-01-25T20:31:23 cannot be represented in the millisecond form. In practice, this limitation has not been a problem.
The first three formats above can also be used with an explicit time zone.
An explicit time zone can be specified as
Z to indicate UTC or by using an offset
in hours and minutes. For example:
2012-01-12T01:37Z 2012-01-12T01:37-00:00 2012-01-12T01:37-07:00 2012-01-12T01:37-07:42
A common format recommended for logs at Netflix is an ISO timestamp in UTC:
These can be copy and pasted to quickly check a graph for a timestamp from a log
file. For practical purposes in Atlas a
-00:00 offset timezone can be thought of
as UTC, but depending on the source may have some
Relative times consist of a named time used for an anchor and an offset duration.
<named=time> '-' <duration> <named-time> '+' <duration>
|now-1w||One week ago.|
|e-1w||One week before the end time.|
|s+6h||Six hours after the start time.|
|s+P2DT6H5M||Two days, 6 hours, and 5 minutes after the start time.|
Duration vs Period¶
This section is using the definition of duration and period from the java time libraries. In short:
- Durations are a fixed number of seconds.
- Periods represent a length of time in a given calendar. For example, the length of a day will vary if there is a daylight savings transition.
The offset used for relative times in Atlas are durations because:
- It is primarily focused on shorter time spans (~ 2 weeks) where drift is less of an issue. In this range the variation is most commonly seen for the daylight savings time transitions.
- For time shifts day over day and week over week are the most common for operational purposes. During daylight savings time transitions a fixed duration seems to cause the least confusion, especially when the transition time is within the window being displayed. The primary use-case where periods were found to be more beneficial and less confusing is for week over week when looking at a small window that does not include the transition. In those cases if the signal reflects human behavior, such as playing movies, then the week over week pattern will typically line up better if using a period.
A simple offset uses a positive integer followed by one of these units:
All durations are a fixed number of seconds. A day is 24 hours, week is 7 days, month is 30 days, and a year is 365 days.
The duration can also be specified as an
ISO duration string, but day (
is the largest part that can be used within the duration. Others such as week (
M), and year (
Y) are not supported. Examples:
|P1D||One day of exactly 24 hours.|
|P1DT37M||One day and 37 minutes.|
|PT5H6M||Five hours and six minutes.|
For more details see docs on parsing durations.