Skip to main content

Creating and Managing Dashboards

1. Creating New Dashboard

Example: Create a new dashboard from scratch

{
  "dashboard": {
    "title": "My New Dashboard",
    "tags": ["monitoring", "production"],
    "timezone": "browser",
    "schemaVersion": 36
  },
  "panels": [],
  "templating": {
    "list": []
  }
}
Property Description Default
title Name of the dashboard Untitled
tags Tags for organizing dashboards []
timezone Timezone for dashboard display browser
schemaVersion Version of the dashboard schema 36
Note: Grafana dashboards are JSON objects that define the structure and content of a dashboard.

Workflow: Creating a New Dashboard in Grafana

  1. Navigate to the Grafana dashboard list page
  2. Click + New Dashboard
  3. Select New dashboard or Import dashboard
  4. Configure basic dashboard settings (title, tags, timezone)
  5. Add panels to visualize data

2. Saving Dashboard

Option Values Notes
dashboard.title "My Dashboard" Title of the dashboard
dashboard.uid "my-dashboard-uid" Unique identifier for the dashboard
dashboard.folderId 1 Folder ID where the dashboard is saved
dashboard.isStarred false Whether the dashboard is starred
dashboard.version 1 Version of the dashboard

Example: Saving a Dashboard via API

{
  "dashboard": {
    "title": "My Dashboard",
    "uid": "my-dashboard-uid",
    "folderId": 1,
    "isStarred": false,
    "version": 1
  },
  "overwrite": true
}
Note: The overwrite parameter determines whether to overwrite an existing dashboard with the same UID.

3. Configuring Dashboard Settings

Setting Description Default Value Notes
title Dashboard title displayed in the UI Untitled Dashboard Required field
uid Unique identifier for the dashboard Auto-generated Used in URLs and API calls
tags Tags for organizing and searching dashboards None Comma-separated list of tags
timezone Timezone used for time-based queries and display Browser Options: 'browser', 'utc', or custom timezone
refresh Auto-refresh interval for panels Off Format: '5s', '1m', etc.
editable Whether dashboard can be edited true Set to false to lock dashboard
schemaVersion Version of the dashboard schema 36 Incremented when schema changes
version Dashboard version for tracking changes 0 Auto-incremented on save

Example: Setting Dashboard Timezone

{
  "title": "Production Metrics",
  "timezone": "utc",
  "refresh": "30s"
}
Note: The uid field is required when importing dashboards via JSON.
Warning: Setting editable to false prevents any changes to the dashboard in the UI.

4. Setting Dashboard Time Range

Property Value Description
timepicker true Enables the time range picker in the dashboard
time.from now-1h Start time for the dashboard, supports relative and absolute values
time.to now End time for the dashboard, supports relative and absolute values

Example: Setting Default Time Range

{
  "time": {
    "from": "now-6h",
    "to": "now"
  }
}
Note: Time range values can use relative formats like now-1h or absolute timestamps in ISO format.
Property Value Description
links [] Array of link objects to be added to the dashboard
{
  "links": [
    {
      "title": "Grafana Documentation",
      "url": "https://grafana.com/docs/",
      "targetBlank": true
    }
  ]
}
{
  "links": [
    {
      "title": "Infrastructure Metrics",
      "url": "/d/infrastructure-metrics-dashboard",
      "targetBlank": false
    }
  ]
}

6. Managing Dashboard Versions

Version Description Actions Notes
v1.0 Initial dashboard version Save Base configuration and panels
v1.1 Added new metrics panel Save as New Version Includes latency and error rate charts
v1.2 Updated data sources Save as New Version Changed from Prometheus to Loki
v2.0 Major redesign with new layout Save as New Version Improved dashboard performance and UI

Example: Version Control in Grafana

{
  "dashboard": {
    "id": 12345,
    "version": 2,
    "title": "Production Metrics Dashboard",
    "panels": [
      {
        "id": 1,
        "type": "graph",
        "title": "Request Latency"
      },
      {
        "id": 2,
        "type": "stat",
        "title": "Error Rate"
      }
    ]
  },
  "revisions": [
    {
      "version": 1,
      "timestamp": "2025-04-01T10:00:00Z",
      "changes": "Initial setup"
    },
    {
      "version": 2,
      "timestamp": "2025-04-05T14:30:00Z",
      "changes": "Added new panels and updated data sources"
    }
  ]
}
Note: Grafana supports versioning through built-in revision history. Each dashboard save creates a new version, which can be restored or compared.
Warning: Reverting to an older version may cause loss of recent panel configurations or data source changes.

Version Management Summary

  • NEW Versioning is enabled by default in Grafana
  • Each save creates a new version with timestamp
  • Version history can be accessed via the dashboard settings menu
  • Restoring a version is possible through the UI or API

7. Setting Dashboard Permissions

Permission Description Level Notes
Dashboard:Read Allows reading dashboard content and metadata Viewer Default permission for viewers
Dashboard:Write Allows editing and saving dashboard changes Editor Required to modify dashboards
Dashboard:Delete Allows deleting dashboards Admin Highly restricted permission
Dashboard:Create Allows creating new dashboards Editor Requires write access to create

Example: Setting Dashboard Permissions via API

curl -X POST "http://localhost:3000/api/dashboards/uid/my-dashboard-permissions" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d &#x27;{
    "dashboardId": 123,
    "permission": "Edit",
    "role": "Editor"
  }&#x27;
Note: Permissions can also be set through the Grafana UI under Dashboard Settings > Permissions.
Warning: Be cautious when granting Dashboard:Delete permissions as it allows removal of critical dashboards.

8. Organizing with Folders

Folder Description Usage
Name Unique identifier for the folder Used to group dashboards logically
UID Unique ID for the folder (auto-generated) Used in API calls and URL paths
Parent Folder Optional parent folder for hierarchy Enables nested organization

Example: Creating a Folder via API

{
  "title": "Production Dashboards",
  "uid": "prod-dashboards"
}

Workflow: Organizing Dashboards in Folders

  1. Create a new folder in the Grafana UI or via API
  2. Assign dashboards to the folder by editing their settings
  3. Use folder permissions to control access to dashboards within

Best Practices for Folder Organization

  • Use descriptive folder names to reflect the dashboard content or environment
  • Implement a hierarchical structure for large numbers of dashboards
  • Apply consistent naming conventions across folders and dashboards

9. Using Dashboard Tags

Tag Description Usage
environment Indicates the environment a dashboard belongs to (e.g., production, staging) "environment": "production"
team Identifies the team responsible for the dashboard "team": "backend"
service Specifies the service or application the dashboard monitors "service": "auth-service"

Example: Adding Tags to a Dashboard

{
  "title": "API Performance Dashboard",
  "tags": [
    "api",
    "performance",
    "backend"
  ],
  "folderId": 1
}
Note: Tags can be used to filter dashboards in the Grafana UI and via API.

Tag Management Best Practices

  • Use consistent tag naming conventions across your organization
  • Tags should be descriptive and relevant to the dashboard's purpose
  • Avoid overly generic tags like dashboard or monitoring
  • Use tags to group dashboards by environment, team, or service

10. Starring Favorite Dashboards

Starring dashboards in Grafana allows you to quickly access your most frequently used dashboards from the dashboard list.

Property Description Default Value
Starred Dashboards Indicates whether a dashboard is starred false

Example: Star a Dashboard via UI

1. Navigate to the dashboard you want to star.
2. Click the star icon in the top right corner of the dashboard header.
3. The star will turn yellow, indicating the dashboard is starred.

Example: Unstar a Dashboard via UI

1. Navigate to the starred dashboard.
2. Click the yellow star icon in the top right corner of the dashboard header.
3. The star will turn gray, indicating the dashboard is no longer starred.
Note: Starred dashboards are saved per user and will appear at the top of the dashboard list when you filter by "Starred".

Was this article helpful?