Wandering Thoughts archives

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 post gives us our first use of '+' to show us today from 8am until now:

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.