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
- Navigate to the Grafana dashboard list page
- Click
+ New Dashboard - Select
New dashboardorImport dashboard - Configure basic dashboard settings (title, tags, timezone)
- 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 |
Note: Time range values can use relative formats like
now-1h or absolute timestamps in ISO format.
5. Adding Dashboard Links
| Property | Value | Description |
|---|---|---|
| links | [] |
Array of link objects to be added to the dashboard |
Example: Adding a link to an external documentation site
{
"links": [
{
"title": "Grafana Documentation",
"url": "https://grafana.com/docs/",
"targetBlank": true
}
]
}
Example: Adding a link to another dashboard
{
"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 '{
"dashboardId": 123,
"permission": "Edit",
"role": "Editor"
}'
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 |
Workflow: Organizing Dashboards in Folders
- Create a new folder in the Grafana UI or via API
- Assign dashboards to the folder by editing their settings
- 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
dashboardormonitoring - 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".