Dashboard Time Controls

Introduction

Time controls are a fundamental component of Grafana dashboards, allowing users to define specific time ranges for visualizing time series data. These controls enable you to zoom into specific time periods, compare different time ranges, and create dynamic views of your metrics and logs. Understanding how to effectively use time controls is essential for anyone working with Grafana dashboards.

In this guide, we'll explore the various time control features in Grafana, how to configure them, and how they can be used to enhance your data analysis workflows.

Understanding the Time Picker

At the top of every Grafana dashboard, you'll find the time picker - a powerful tool that controls the time range for all panels in your dashboard.

Basic Time Picker Features

The time picker consists of several components:

1. Current time range display - Shows the currently selected time range
2. Quick ranges - Predefined time ranges like "Last 5 minutes", "Last 12 hours", etc.
3. Relative time range options - Options like "Last 30 days" or "Last 6 months"
4. Absolute time range selector - Calendar interface for selecting specific dates and times
5. Refresh interval selector - Controls how often the dashboard data refreshes

Using Quick Ranges

Quick ranges provide a convenient way to switch between commonly used time periods:

jsx

// This is represented in the UI as buttons, not actual code
"Last 5 minutes"
"Last 15 minutes"
"Last 30 minutes"
"Last 1 hour"
"Last 3 hours"
"Last 6 hours"
"Last 12 hours"
"Last 24 hours"

When you click on any of these options, all panels in your dashboard will update to display data for the selected time range.

Relative Time Ranges

Relative time ranges are specified in relation to the current time:

jsx

// Examples of relative time range expressions
"now-1h" // From 1 hour ago to now
"now-6h" // From 6 hours ago to now
"now-7d" // From 7 days ago to now
"now-30d" // From 30 days ago to now
"now-90d" // From 90 days ago to now
"now-6M" // From 6 months ago to now
"now-1y" // From 1 year ago to now

You can combine these expressions to create custom time ranges:

jsx

"now-1h to now" // From 1 hour ago to now
"now-24h to now-12h" // From 24 hours ago to 12 hours ago
"now-7d to now-1d" // From 7 days ago to 1 day ago

Configuring Time Zones

Grafana allows you to work with different time zones, which is particularly useful for distributed teams or when monitoring systems across different geographical locations.

You can configure time zones in three places:

1. User preferences - Set your default time zone
2. Dashboard settings - Override the time zone for a specific dashboard
3. Time picker - Temporarily change the time zone when viewing a dashboard

To change the time zone in the time picker:

1. Click on the time picker
2. Select the "Time zone" dropdown
3. Choose from options like "Browser Time", "UTC", or other specific time zones

Using Time Range Controls in Panels

While the dashboard time picker applies to all panels, you can also configure time-related settings for individual panels.

Time Shift

Time shift allows you to offset the time range for a specific panel relative to the dashboard time. This is useful for comparing current data with historical data.

For example, to compare current metrics with metrics from one week ago:

1. Edit your panel
2. Go to the "Query" tab
3. Find the "Time shift" option
4. Enter 1w to shift the time range back by one week

Other time shift examples:

jsx

"1h" // Shift back by 1 hour
"6h" // Shift back by 6 hours
"1d" // Shift back by 1 day
"7d" // Shift back by 1 week
"1M" // Shift back by 1 month

Time Overrides

You can also completely override the dashboard time range for a specific panel:

1. Edit your panel
2. Go to the "Query" tab
3. Enable "Time range" override
4. Set a custom relative or absolute time range

Time Range Controls for Variables

Grafana variables can be time-based, allowing you to create dynamic dashboards that adjust based on the selected time range.

Creating a Time-Based Variable

1. Go to Dashboard Settings > Variables
2. Click "Add variable"
3. Choose "Time range" as the type
4. Configure the variable options:
   • Name: A descriptive name like timeRange
   • Label: The display name in the dashboard
   • Values: Define the available time ranges

Example configuration:

jsx

Name: timeRange
Type: Time range
Label: Time Range
Values: 
  - Last 5 minutes
  - Last 30 minutes
  - Last 1 hour
  - Last 6 hours
  - Last 12 hours
  - Last 24 hours

You can then use this variable in your queries to dynamically adjust the time range:

sql

SELECT value FROM metrics WHERE time > $__timeFrom() AND time < $__timeTo()

Auto-Refresh Controls

Grafana's auto-refresh feature allows dashboards to update automatically at set intervals, which is particularly useful for operational monitoring.

Setting Auto-Refresh

To configure auto-refresh:

1. Click on the time picker
2. Select the "Refreshing every" dropdown
3. Choose from options like "Off", "5s", "10s", "30s", "1m", "5m", etc.

When auto-refresh is enabled, Grafana will reload the dashboard data at the specified interval.

Auto-Refresh Best Practices

• Performance considerations: Very frequent refreshes (e.g., every 5 seconds) can put significant load on your data sources
• Time range impact: Choose refresh intervals appropriate for your time range (e.g., longer intervals for longer time ranges)
• Browser impact: Auto-refreshing dashboards consume browser resources, which is important to consider for dashboards displayed on TVs or monitoring screens

Practical Examples

Let's explore some real-world scenarios where time controls are particularly useful.

Example 1: Incident Investigation

When investigating an incident:

1. Start with a broad time range (e.g., "Last 24 hours") to identify when the issue began
2. Zoom in to the specific time period (e.g., "Last 3 hours") where the incident occurred
3. Use the time shift feature to compare current metrics with metrics from a similar period before the incident
4. Enable auto-refresh (e.g., every 30 seconds) to monitor the situation in real-time

Example 2: Daily Operations Dashboard

For a daily operations dashboard:

1. Set the default time range to "Today so far" or "Last 24 hours"
2. Create time-based variables for common time periods your team needs to analyze
3. Configure auto-refresh to update every 5 minutes
4. Use time overrides for specific panels that need to show longer-term trends

Example 3: Comparing Time Periods

To compare this week's metrics with last week's:

1. Create a dashboard with duplicated panels
2. Apply a time shift of "1w" to the duplicated panels
3. Use the dashboard time picker to focus on specific days or hours
4. Add annotations to mark important events for context

Advanced Time Range Features

Annotations Based on Time

Annotations allow you to mark points in time on your graphs, providing context for specific events:

1. Configure an annotation data source (e.g., a database query that returns timestamps and descriptions)
2. Add the annotation to your dashboard
3. The annotations will appear as vertical lines or markers on your time series graphs

Example annotation query (SQL):

sql

SELECT 
  time_column as time,
  description as text,
  tags
FROM events
WHERE time_column BETWEEN $__timeFrom() AND $__timeTo()

Zoom and Time Range Selection

You can zoom into specific time ranges directly from graph panels:

1. Click and drag across a section of a graph to select that time range
2. Use the "Apply time range" option that appears to update the dashboard time
3. Alternatively, use the magnifying glass icons to zoom in or out

Common Time Control Patterns

Daily Operations

For daily operations monitoring, consider these time control patterns:

• Default to "Today so far" or "Last 24 hours"
• Add quick access to "Yesterday" for easy comparison
• Set auto-refresh to 1 or 5 minutes

Weekly Reports

For weekly reporting dashboards:

• Default to "This week so far" or "Last 7 days"
• Add comparison with "Previous week"
• Disable auto-refresh as these are typically used for analysis rather than real-time monitoring

Incident Response

For incident response dashboards:

• Allow very fine-grained time selection (minutes, not hours)
• Enable quick switching between short-term views (last few minutes) and longer context (last few hours)
• Set aggressive auto-refresh (5-10 seconds) during active incidents

Time Controls in Dashboard JSON

For advanced users or programmatic dashboard creation, you can define time controls in the dashboard JSON configuration:

json

"time": {
  "from": "now-6h",
  "to": "now"
},
"timezone": "browser",
"refresh": "5s",
"timepicker": {
  "refresh_intervals": ["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"],
  "time_options": ["5m", "15m", "1h", "6h", "12h", "24h", "2d", "7d", "30d"]
}

Troubleshooting Time Controls

Common Issues

1. Data appears outside the selected time range: Some data sources may return data points slightly outside your specified range due to how they handle time boundaries
2. Time zones confusion: Mismatches between browser time zone, dashboard time zone, and data source time zone can lead to unexpected results
3. Auto-refresh not working: Network issues or browser tab being in background can affect auto-refresh

Solutions

1. For boundary issues, try adjusting your queries to strictly enforce time boundaries
2. Explicitly set time zones at the dashboard level for consistency
3. Check browser console for errors if auto-refresh isn't working as expected

Summary

Time controls are a powerful feature of Grafana dashboards that allow you to:

• Focus on specific time periods for detailed analysis
• Compare metrics across different time ranges
• Automatically refresh data for real-time monitoring
• Create dynamic dashboards that adjust based on selected time ranges

Mastering time controls will significantly enhance your ability to extract insights from your time series data and create more effective monitoring solutions.

Additional Resources

• Experiment with different time ranges on a test dashboard to see how they affect your visualizations
• Try creating a dashboard with time-shifted panels to compare current metrics with historical data
• Set up auto-refresh at different intervals to understand the performance impact

Exercise

Create a dashboard that shows the following:

1. A main graph of system metrics for the last 24 hours
2. A second graph showing the same metrics but time-shifted by 1 week for comparison
3. A variable that allows switching between different time ranges
4. Auto-refresh configured to update every minute
5. Annotations marking important system events

This exercise will help you apply the time control concepts covered in this guide and create a practical monitoring dashboard.