Organizing Dashboards with Folders

As your Grafana usage grows, you'll quickly accumulate dashboards for different teams, projects, and environments. Without organization, finding the right dashboard becomes challenging. In this lesson, you'll learn how to use folders to create a logical structure for your dashboards, making them easier to manage and share.

Learning Goals:

• Create and manage dashboard folders
• Understand folder permissions and inheritance
• Organize dashboards using a consistent structure
• Use folders with dashboard variables and searches

Creating Your First Folder

Folders in Grafana provide a way to group related dashboards together. Let's start by creating a folder through the Grafana UI.

Using the Grafana Interface

1. Navigate to the Dashboards section in the main menu
2. Click on + New and select New folder
3. Enter a descriptive name like "Production Monitoring"
4. Click Create

tip

Use consistent naming conventions for folders. For example: Team-Environment-System format like Backend-Production-API or Frontend-Staging-WebApp.

Creating Folders via API

You can also create folders programmatically using the Grafana API:

create-folder.sh

#!/bin/bash

GRAFANA_URL="http://localhost:3000"
API_KEY="your-api-key-here"

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "prod-monitoring",
    "title": "Production Monitoring"
  }' \
  "$GRAFANA_URL/api/folders"

Folder Structure Best Practices

A well-organized folder structure makes your dashboards more discoverable and maintainable. Here are some common patterns:

By Environment

📁 Production
  📊 API Response Times
  📊 Database Performance
  📊 Infrastructure Health
📁 Staging
  📊 API Response Times
  📊 Database Performance
📁 Development
  📊 Developer Metrics

By Team or Service

📁 Backend Team
  📁 Production
  📁 Staging
📁 Frontend Team  
  📁 Production
  📁 Staging
📁 Infrastructure Team
  📁 Kubernetes
  📁 Networking

Managing Folder Permissions

Folders inherit permissions from the organization level, but you can customize them for specific teams or users.

Setting Folder Permissions via UI

1. Navigate to your folder
2. Click the Permissions tab
3. Add users or teams with appropriate access levels:
   • Viewer: Can only view dashboards
   • Editor: Can create and edit dashboards
   • Admin: Full control over the folder

Programmatic Permission Management

set-folder-permissions.py

import requests

def set_folder_permissions(folder_uid, team_id, permission_level):
    url = f"http://localhost:3000/api/folders/{folder_uid}/permissions"
    headers = {
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json"
    }
    
    data = {
        "items": [
            {
                "teamId": team_id,
                "permission": permission_level
            }
        ]
    }
    
    response = requests.post(url, json=data, headers=headers)
    return response.status_code == 200

# Example usage
set_folder_permissions("prod-monitoring", 1, 1)  # 1 = View permission

Moving Dashboards Between Folders

As your organization evolves, you may need to reorganize your dashboards.

Using the Dashboard Settings

1. Open the dashboard you want to move
2. Click the Dashboard settings (gear icon)
3. Under General, find the Folder dropdown
4. Select the target folder and click Save

Bulk Operations with API

move-dashboards.sh

#!/bin/bash

# Move all dashboards from one folder to another
SOURCE_FOLDER="old-folder"
TARGET_FOLDER="new-folder"
GRAFANA_URL="http://localhost:3000"

# Get all dashboards from source folder
DASHBOARDS=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "$GRAFANA_URL/api/search?folderIds=1&query=&starred=false")

echo "$DASHBOARDS" | jq -r '.[] | "\(.uid) \(.title)"' | while read uid title; do
  echo "Moving dashboard: $title"
  
  # Update dashboard folder
  curl -X PUT \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"folderUid\": \"$TARGET_FOLDER\"}" \
    "$GRAFANA_URL/api/dashboards/uid/$uid"
done

Using Folders with Dashboard Variables

Folders can be used in template variables to create dynamic dashboard lists:

folder-variable.json

{
  "dashboard": {},
  "templating": {
    "list": [
      {
        "name": "folder",
        "type": "custom",
        "query": "Production, Staging, Development",
        "options": [],
        "includeAll": true,
        "multi": false,
        "current": {
          "text": "Production",
          "value": "Production"
        }
      }
    ]
  }
}

Searching and Filtering by Folder

Grafana's search functionality respects folder organization:

Search Examples

• production latency - Search all folders
• folder:Production latency - Search only in Production folder
• folder:Backend-Team environment:staging - Team and environment filtering

warning

Dashboard searches only look at dashboard titles and tags, not the content of panels or queries. Make sure to use descriptive titles and consistent tagging.

Common Pitfalls

• Over-nesting folders: Too many levels make navigation difficult. Stick to 2-3 levels maximum.
• Inconsistent naming: Mixing naming conventions (team-project vs project-team) causes confusion.
• Permission sprawl: Adding too many individual user permissions instead of using teams.
• Ignoring folder UIDs: Using auto-generated UIDs instead of setting meaningful ones makes API operations harder.
• Not planning for growth: Creating a structure that doesn't scale as your organization adds more services.

Summary

Folders are essential for maintaining an organized and scalable Grafana instance. By grouping related dashboards, setting appropriate permissions, and using consistent naming conventions, you can ensure that your monitoring remains accessible and manageable as your organization grows. Remember to plan your folder structure carefully and use teams for permission management rather than individual users.

Quiz

Show quiz

1. What is the primary benefit of using folders in Grafana?

   • A) Improved dashboard performance
   • B) Better organization and access control
   • C) Automatic dashboard backup
   • D) Enhanced visualization options

2. Which permission level allows users to create and edit dashboards in a folder?

   • A) Viewer
   • B) Editor
   • C) Admin
   • D) Creator

3. What is a recommended practice for folder naming conventions?

   • A) Use random names for security
   • B) Follow a consistent pattern like Team-Environment-Service
   • C) Use only numbers for easy sorting
   • D) Avoid using special characters at all costs

4. How can you move multiple dashboards between folders efficiently?

   • A) Manually through the UI one by one
   • B) Using the Grafana API with bulk operations
   • C) Export and re-import all dashboards
   • D) Contact Grafana support for assistance

5. What happens to dashboard permissions when you move a dashboard to a new folder?

   • A) They are copied from the source folder
   • B) They are inherited from the new folder
   • C) They remain unchanged
   • D) They are reset to organization defaults

---

Answers:

1. B) Better organization and access control
2. B) Editor
3. B) Follow a consistent pattern like Team-Environment-Service
4. B) Using the Grafana API with bulk operations
5. B) They are inherited from the new folder