Skip to content

N
nexpie-grafana-theme
Commit 26964b38 by Diana Payton Committed by GitHub
Options

Docs: Update time range controls (#24709) 

* moved file and updated menu

* Delete timerange.md

* Update menu.yaml

* Update time-range-controls.md

* fixed links

* Update time-range-controls.md

* content updates

* Update time-range-controls.md

* Apply suggestions from code review

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update docs/sources/dashboards/time-range-controls.md

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update time-range-controls.md

* Update docs/sources/dashboards/time-range-controls.md

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update docs/sources/dashboards/time-range-controls.md

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update docs/sources/dashboards/time-range-controls.md

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* Update time-range-controls.md

Co-authored-by: Daniel Lee <dan.limerick@gmail.com>
Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
parent f8801952
Showing with 123 additions and 94 deletions
docs/sources/dashboards/time-range-controls.md 0 → 100644
+++
title = "Time range controls"
keywords = ["grafana", "dashboard", "documentation", "time range"]
type = "docs"
[menu.docs]
aliases = ["/docs/grafana/latest/reference/timerange/"]
name = "Time range controls"
parent = "dashboards"
weight = 7
+++
# Time range controls
Grafana provides several ways to manage the time ranges of the data being visualized, both at the dashboard level and the panel level.
This page describes supported time units and relative ranges, the common time controls, dashboard-wide time settings, and panel-specific time settings.
## Time units and relative ranges
The following time units are supported: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, and `y (years)`.
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 plus operator allows you to step forward in time relative to now. You might use this feature to look at predicted data in the future, for example.
Here are some examples:
Example relative range | From: | To:
-------------- | ----- | ---
Last 5 minutes | `now-5m` | `now`
The day so far | `now/d` | `now`
This week | `now/w` | `now/w`
Week to date | `now/w` | `now`
Previous Month | `now-1M/M` | `now-1M/M`
## Common time range controls
The dashboard and panel time controls have a common user interface (UI).
<img class="no-shadow" src="/img/docs/time-range-controls/common-time-controls-7-0.png" max-width="700px">
The options are defined below.
### Current time range
The current time range, also called the _time picker_, shows the time range currently displayed in the dashboard or panel you are viewing.
Hover your cursor over the field to see the exact time stamps in the range and their source (such as the local browser).
<img class="no-shadow" src="/img/docs/time-range-controls/time-picker-7-0.png" max-width="300px">
Click on the current time range to change the time range. You can change the current time using a _relative time range_, such as the last 15 minutes, or an _absolute time range_, such as `2020-05-14 00:00:00 to 2020-05-15 23:59:59`.
<img class="no-shadow" src="/img/docs/time-range-controls/change-current-time-range-7-0.png" max-width="900px">
### Relative time range
Select the relative time range from the **Relative time ranges** list. Some examples of time ranges are:
- Last 30 minutes
- Last 12 hours
- Last 7 days
- Last 2 years
- Yesterday
- Day before yesterday
- This day last week
- Today so far
- This week so far
- This month so far
### Absolute time range
Set an absolute time range one of two ways:
- Type values into the **From** and **To** fields. You can type exact time values or relative values, such as `now-24h`, and then click **Apply time range**.
- Click in the **From** or **To** field. Grafana displays a calendar. Click the day or days you want to use as the current time range and then click **Apply time range**.
This section also displays recently used absolute ranges.
### Zoom out (Cmd+Z or Ctrl+Z)
Click the **Zoom out** icon to view a larger time range in the dashboard or panel visualization.
### Zoom in (only applicable to graph visualizations)
Click and drag to select the time range in the visualization that you want to view.
### Refresh dashboard
Click the **Refresh dashboard** icon to immediately run every query on the dashboard and refresh the visualizations.
By default, Grafana does not automatically refresh the dashboard. Queries run on their own schedule according to the panel settings. However, if you want to to regularly refresh the dashboard, then click the down arrow next to the **Refresh dashboard** icon and then select a refresh interval.
## Dashboard time settings
Time settings are saved on a per-dashboard basis.
To access the dashboard time settings, click the **Dashboard settings** (gear) icon at the top of the screen. The settings are in the **Time Options** section of the General tab.
- **Timezone -** Specify the local time zone of the service or system that you are monitoring. This can be helpful when monitoring a system or service that operates across several time zones.
- **Default -** The default selected time zone for the user profile, team, or organization is used. If no time zone is specified for the user profile, a team the user is a member of, or the organization, then Grafana uses local browser time.
- **Local browser time -** The time zone configured for the viewing user browser is used. This is usually the same time zone as set on the computer.
- Standard [ISO 8601 time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), including UTC.
- **Auto-refresh -** Customize the options displayed for relative time and the auto-refresh options. Entries are comma separated and accept any valid time unit.
- **Now delay now- -** Override the `now` value by entering a time delay. Most commonly, this feature is used to accommodate known delays in data aggregation to avoid null values.
- **Hide time picker -** Select this option if you do not want Grafana to display the time picker.
## Panel time overrides and timeshift
In [Query options]({{< relref "queries.md#query-options" >}}), you can override the relative time range for individual panels, causing them to be different than what is selected in the dashboard time picker in the upper right. This allows you to show metrics from different time periods or days at the same time.
## Control the time range using a URL
Time range of a dashboard can be controlled by providing following query parameters in the dashboard URL:
- `from` - defines lower limit of the time range, specified in ms epoch or [relative time]({{< relref "#relative-time-range" >}})
- `to` - defines upper limit of the time range, specified in ms epoch or [relative time]({{< relref "#relative-time-range" >}})
- `time` and `time.window` - defines a time range from `time-time.window/2` to `time+time.window/2`. Both params should be specified in ms. For example `?time=1500000000000&time.window=10000` will result in 10s time range from 1499999995000 to 1500000005000
docs/sources/features/dashboard/dashboards.md
......@@ -39,7 +39,7 @@ The image above shows you the top header for a Dashboard.
## Manage dashboards
The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../../reference/timerange.md" >}}) in the upper right of the dashboard.
The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../../dashboards/time-range-controls.md" >}}) in the upper right of the dashboard.
Dashboards can use [templating]({{< relref "../../variables/templates-and-variables.md" >}}) to make them more dynamic and interactive.
......
docs/sources/features/panels/graph.md
......@@ -187,7 +187,7 @@ Time regions allow you to highlight certain time regions of the graph to make it
The time range tab allows you to override the dashboard time range and specify a panel specific time.
Either through a relative from now time option or through a timeshift.
Panel time overrides and timeshift are described in more detail [here]({{< relref "../../reference/timerange.md#panel-time-overrides-timeshift" >}}).
Panel time overrides and timeshift are described in more detail [here]({{< relref "../../dashboards/time-range-controls.md" >}}).
### Data links
......
docs/sources/menu.yaml
......@@ -185,8 +185,8 @@
name: Sharing a dashboard
- link: /reference/share_panel/
name: Sharing a panel
- link: /reference/timerange/
name: Time range
- link: /dashboards/time-range-controls/
name: Time range controls
- link: /reference/export_import/
name: Export and import
- link: /features/dashboard/links/
......
docs/sources/panels/queries.md
......@@ -76,7 +76,7 @@ In addition to the data sources that you have configured in your Grafana, there
Click **Query options** next to the data source selector to see settings for your selected data source. Changes you make here affect only queries made in this panel.
{{< docs-imagebox img="/img/docs/queries/data-source-options-7-0.png" class="docs-image--no-shadow" max-width="400px" >}}
{{< docs-imagebox img="/img/docs/queries/data-source-options-7-0.png" class="docs-image--no-shadow" max-width="1000px" >}}
Grafana sets defaults that are shown in dark gray text. Changes are displayed in white text. To return a field to the default setting, delete the white text from the field.
......
docs/sources/reference/timerange.md deleted 100755 → 0
+++
title = "Time Range"
keywords = ["grafana", "dashboard", "documentation", "time range"]
type = "docs"
[menu.docs]
name = "Time Range"
parent = "dashboard_features"
weight = 7
+++
# Time Range Controls
Grafana provides numerous ways to manage the time ranges of the data being visualized, both at the Dashboard-level and the Panel-level.
<img class="no-shadow" src="/img/docs/v50/timepicker.png" width="700px">
The two controls for time visualization are available in the top right:
1. **Current time range**: This shows the current dashboard time. You can click on it to change it.
2. **Refresh interval**: This shows the current refresh interval for the current dashboard. You can click on it to change
it. This feature is especially useful for always-on displays so that the most recent data is always shown.
These settings apply to all Panels in the Dashboard (except those with Panel Time Overrides enabled)
## Time Units
The following time units are supported: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, `y (years)`. 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 `/$unit` to the end.
Take a look at some examples to see these concepts in practice:
Example Relative Range | From: | To:
-------------- | ----- | ---
Last 5 minutes | `now-5m` | `now`
The day so far | `now/d` | `now`
This week | `now/w` | `now/w`
Week to date | `now/w` | `now`
Previous Month | `now-1M/M` | `now-1M/M`
## Dashboard Time Options
There are two settings available in the Dashboard Settings General tab, allowing customization of the auto-refresh intervals and the definition of `now`.
<img class="no-shadow" src="/img/docs/v50/time_options.png" width="500px">
### Auto-Refresh Options
It's possible to customize the options displayed for relative time and the auto-refresh options.
From Dashboard settings, click the Timepicker tab. From here you can specify the relative and auto-refresh intervals. The Timepicker tab settings are saved on a per Dashboard basis. Entries are comma separated and accept any valid time unit.
### Defining Now
Grafana offers the ability to override the `now` value on a per dashboard basis. Most commonly, this feature is used to accommodate known delays in data aggregation to avoid null values.
### Time zone options
Starting in version 7.0, you can override the time zone used to display date and time values in a dashboard.
With this feature, you can specify the local time zone of the service or system that you are monitoring. This can be helpful when monitoring a system or service that operates across several time zones.
Apart from the standard [ISO 8601 time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) you can select the following options:
* **Default**: The default selected time zone for the user profile or organization is used. If no time zone is specified for the user profile or the organization, then `Local browser time` is used.
* **Local browser time**: The time zone configured for the viewing user browser is used. This is usually the same time zone as set on the computer.
## Panel time overrides and timeshift
You can override the relative time range for individual panels, causing them to be different than what is selected in the Dashboard time picker in the upper right. This allows you to show metrics from different time periods or days at the same time.
{{< docs-imagebox img="/img/docs/v50/panel_time_override.png" max-width="500px" >}}
You control these overrides in panel editor mode and the tab `Time Range`.
{{< docs-imagebox img="/img/docs/v50/time_range_tab.png" max-width="500px" >}}
When you zoom or change the Dashboard time to a custom absolute time range, all panel overrides will be disabled. The panel relative time override is only active when the dashboard time is also relative. The panel timeshift override is always active, even when the dashboard time is absolute.
The `Hide time override info` option allows you to hide the override info text that is by default shown in the
upper right of a panel when overridden time range options.
**Note:** You can only override the dashboard time with relative time ranges. Absolute time ranges are not available.
## Controlling time range using URL
Time range of a dashboard can be controlled by providing following query parameters in dashboard URL:
- `from` - defines lower limit of the time range, specified in ms epoch
- `to` - defines upper limit of the time range, specified in ms epoch
- `time` and `time.window` - defines a time range from `time-time.window/2` to `time+time.window/2`. Both params should be specified in ms. For example `?time=1500000000000&time.window=10000` will result in 10s time range from 1499999995000 to 1500000005000
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment