Documentation Grafana Cloud Observe and act Test and validate Synthetic Monitoring Create checks Organize checks in folders

Organize checks in folders

As you create more checks or onboard new teams, a single flat list becomes hard to scan. You can organize your Grafana Cloud Synthetic Monitoring checks into Grafana folders to group them by team, service, or environment. This makes the right checks easy to find and lets you act on an entire group at once rather than one check at a time.

Using folders, you can:

• Assign a check to any Grafana folder you can edit, when you create the check or later.
• Browse your checks grouped by folder in the check list, mirroring your Grafana folder hierarchy.
• Move one or more checks between folders at any time.
• Act on all the checks in a folder at once from the folder’s Actions menu: enable, disable, move, or delete them.
• Control who can create, edit, and delete checks in the Synthetics app through Grafana folder permissions.

How it works

Synthetic Monitoring uses standard Grafana folders. A check can live in any folder you can edit, such as your team’s folder, a service folder, or anywhere else in your Grafana folder tree. Every check you create in the Synthetics app is assigned to a folder: the default Grafana Synthetic Monitoring folder is preselected when you can edit it, and you can change it to any other folder you can edit. Checks created without a folder through the API or Terraform are stored in the default folder.

The check list mirrors your real folder hierarchy: folders nest under their parents, whether they live inside the default Grafana Synthetic Monitoring folder or elsewhere in Grafana. As with folders elsewhere in Grafana, you can nest folders up to four levels deep.

Only folders that contain checks appear in the check list.

Before you begin

To organize checks in folders, you need:

• A Grafana Cloud account with Synthetic Monitoring set up.
• Permission to edit checks in Synthetic Monitoring.
• To assign a check to a folder, Edit permission on that folder.
• To create new folders, Edit permission on the parent folder where you want to create them. Creating a folder at the top level (Dashboards) requires organization-level folder creation rights.

Assign a folder when creating a check

1. On the main menu, select Testing & synthetics and then Synthetics.

2. Click Create new check or Add new check.

3. Select your check type and configure its options.

4. In the Folder field on the first step of the check form, select the folder where you want to store the check.

   To create a new folder, click Create folder, enter a name, and select a parent folder.

5. Click Save.

A folder is required: if the preselected folder was cleared or none could be preselected, select one before saving.

Change the folder of an existing check

1. On the main menu, select Testing & synthetics and then Synthetics.
2. Click Checks.
3. Open the check you want to move and click Edit.
4. In the Folder field, select a different folder.
5. Click Save.

You can also move a check without opening the editor: select it in the check list and click Move to folder.

Move multiple checks at once

To move several checks to the same folder:

1. On the main menu, select Testing & synthetics and then Synthetics.
2. Click Checks.
3. Select the checks you want to move using the checkboxes.
4. Click Move to folder and select the destination folder.

All selected checks are moved in a single operation. To perform a bulk move, you need Edit permission on the folder of every selected check, as well as on the destination folder.

Browse checks by folder

The check list offers a folder view in addition to the card and list views:

1. On the main menu, select Testing & synthetics and then Synthetics.
2. Click Checks.
3. Use the view switcher to select the Folder view.

Checks are grouped under their folders, so you can expand only the folders you care about instead of scanning a flat list.

Manage checks at the folder level

In the folder view, every folder has an Actions menu. Its actions apply to the checks you’ve selected in that folder or, when nothing is selected, to every check in the folder, including checks in nested subfolders:

• Enable or disable the checks.
• Move the checks to another folder.
• Delete the checks. Deleting checks doesn’t delete the folder, even when it’s left empty.
• Move folder: relocate the folder itself to another folder you can edit, or to the top level (Dashboards) if you have organization-level folder creation rights. The folder keeps its contents, and its permissions follow the new location.

Actions you don’t have permission for are shown disabled, with the reason.

To rename or delete a folder, or to manage its permissions, use the folder’s Folder actions on the Dashboards page.

Manage check access with folder permissions

You can manage access to checks using folder-level permissions.

Access to checks in a folder is determined by two layers, following the same model as other Grafana resources:

• Synthetic Monitoring role: grants the ability to perform actions in the app, such as reading or writing checks (for example, the Checks reader and Checks writer roles).
• Folder permissions: define which folders those actions can be applied to.

For example:

• A user with folder Edit permission and the Checks writer role can create, edit, move, and delete checks in that folder.
• A user with folder View permission and the Checks writer role can only view the checks in that folder.
• A user with folder Edit permission and the Checks reader role can only view checks, because the effective permission is the lower of the two.
• A user with no access to a folder at all doesn’t see that folder’s checks in the Synthetics app: they’re hidden from the check list, and direct links to them redirect back to the check list.

This follows the same behavior as Grafana folders elsewhere: folder Edit permission allows managing and deleting the resources in the folder, just as it does for dashboards.

Grafana has no deny permissions: grants inherited from a parent folder can’t be removed on its subfolders, and every folder created under the default Grafana Synthetic Monitoring folder inherits its View and Edit grants. To restrict who can see a folder’s checks, use a folder that doesn’t inherit those grants, such as a top-level team folder, and remove the default grants it receives at creation.

Restrict check management to a team’s own folder

To let each team manage (create, edit, and delete) only the checks in their own folder, while keeping all other checks read-only for them:

1. Give each team member the Viewer basic role, not Editor or Admin. The Viewer role already includes the Synthetic Monitoring Checks reader role and folder View.

   Warning

   Team members must not be organization Editors or Admins. Those basic roles grant folder Edit on every folder, so they would be able to edit every team’s checks.

2. Assign each team member the Synthetic Monitoring Checks writer role in Administration > Users. The Viewer basic role doesn’t include this role, so you must add it explicitly.

3. Create a folder for each team.

4. Grant each team folder Edit permission on their own folder:

   1. On the main menu, select Dashboards and navigate to the folder.
   2. Click Folder actions and select Manage permissions.
   3. Click Add a permission and grant the team folder Edit permission.

With this setup, each team can create, edit, move, and delete the checks in their own folder and has read-only access to all other checks.

For more information, refer to Folder access control.

Deleted folders

If a folder containing checks is deleted from Grafana, the checks are automatically moved to the default Grafana Synthetic Monitoring folder and continue to run without interruption.

Provisioning

• API: checks accept a folderUid field on create and update. Any Grafana folder can be used; checks assigned to folders outside the default Grafana Synthetic Monitoring folder appear in the Synthetics app the same way as any other check.
• Terraform: the grafana_synthetic_monitoring_check resource accepts a folder_uid attribute to associate the check with any Grafana folder (requires Grafana Terraform provider v4.37.0 or later). Checks created without a folder_uid are stored in the default Grafana Synthetic Monitoring folder.