Some notes on Grafana relative time ranges
I recently read Grafana's Pro tip: How to use semi-relative time ranges in Grafana and discovered a new feature in Grafana's time range controls, which is that you can get time ranges rounded off to, for example, days. This is what Grafana uses to implement time range choices like 'yesterday', but the exact behavior is not well covered in the documentation. So here is what I've worked out.
To start with, the current documentation says this:
The minus operator allows you to step back in time, relative to now. If you wish to display the full period of the unit (day, week, month, etc…), append
/<time unit>to the end.
The name for right now is '
now', and the simplest version of the
minus operator is that '
now - 6h' means six hours ago. Although
it's not documented, Grafana does accept a '
+' operator here as
well; this steps forward the indicated amount of time. The blog
gives us our first use of '
+' to show us today from 8am until
Start time: now/d + 8h End time: now
The behavior of '/' changes depending on whether it's in the start time or the end time. In the start time, it means the beginning of the rounding unit; in the end time, it means the end of the rounding unit (eg, the beginning of the day and the end of the day, or the beginning of the hour and the end of the hour). This leads us to how 'yesterday' is defined:
Start time: now-1d/d End time: now-1d/d
This is also how the day before yesterday and 'this day last week' work; they use '-2d' and '-7d' respectively. You can do the same thing with other units to get, for example, 'the previous (full) hour', which is 'now-1h/h' for both the start and the end times.
Grafana allows you to move the '/<unit>' around, so you can also write the 'yesterday' start and end times as 'now/d - 1d'. This is a necessary step if you want a time range that is 'yesterday between 8am and 6pm', which is:
Start time: now/d - 16h End time: now/d - 30h
Wait, what? Let's work this out. First, 'now/d' in the start time means 'today at 00:00', so we want to subtract 16 hours to get yesterday at 8am. But 'now/d' in the end time means 'tonight at 23:59:59', so we need to subtract 24 hours to get back to 'today at 00:00' and then another six hours to get back to yesterday at 6pm. Fortunately we can rewrite this to have two steps to make it clearer (although again this is not officially documented):
Start time: now/d -1d +8h End time: now/d -1d -6h
Our start time is eight hours after the start of yesterday at 00:00, while our end time is six hours before the end of yesterday. We can write a similar but simpler version for 'today between 8am and 6pm', with 'now/d +8h' as the start time and 'now/d - 6h' as the end time.
Where the '
/<unit>' can go and still work in such compound
expressions is weird and not clear to me. It works to write either
the version above or 'now -1d/d +8h' (as the start time), but it
doesn't work to write 'now -1d +8h/d'. And of course this doesn't
support subexpressions in brackets, which might make things clearer.