Grafana Library Panels
Teams often need the same panel on many dashboards. A request error rate chart might belong on the overview page, the service page, and the on-call page. Copying the panel three times creates three versions that drift apart. Library panels solve this by keeping one master copy that every dashboard shares.
The Recipe Card Analogy
A restaurant chain keeps one master recipe card for its signature sauce. Every branch follows that card. When the chef improves the recipe, all branches cook the improved version by morning. A library panel acts as the master card. Dashboards use the panel, and a single edit updates all of them.
+----------------------+
| Library Panel |
| "Error Rate" |
+----+------+------+---+
| | |
+-------+ +---+---+ +-------+
|Overview| |Service| |On-Call |
+--------+ +-------+ +--------+
One edit here updates all three dashboards.
When to Use a Library Panel
- A health indicator appears on several dashboards.
- A standard chart must look identical everywhere, such as a company-wide uptime tile.
- A query changes from time to time, and you want one place to fix it.
Skip library panels for charts that belong to a single dashboard. A normal panel keeps the dashboard self-contained.
Create a Library Panel
- Open a dashboard that contains the panel you want to share.
- Open the panel menu and choose More.
- Select New library panel.
- Type a clear name, such as Error Rate - Web.
- Pick a folder for the panel.
- Click Create library panel.
The panel on your dashboard now links to the library copy. A small icon in the panel editor confirms the link.
Add a Library Panel to Another Dashboard
Open the target dashboard in edit mode. Click Add and choose Import from library. Search by name, select the panel, and place it on the grid. The new panel shows the same query, the same visual options, and the same thresholds as the master.
Edit a Library Panel
Open any dashboard that uses the panel and edit it as usual. Grafana warns you that the change affects every dashboard that uses the panel. Save the panel, and the change spreads everywhere at once.
Before edit: Threshold = 5% (all three dashboards)
Edit once: Threshold = 2%
After edit: Threshold = 2% (all three dashboards)
Review the usage list before you edit a widely shared panel. A small colour change is harmless, but a changed query alters the story on every page.
See Where a Panel Is Used
Open Dashboards and select Library panels. Each entry lists its name, its folder, and a count of the dashboards that use it. Click an entry to see the dashboards by name. Use this view to plan changes and to find forgotten panels.
Unlink a Library Panel
A dashboard sometimes needs a private variation. Open the panel menu, choose More, and select Unlink library panel. Grafana converts the panel into a normal panel on that dashboard. The master copy stays untouched, and later master edits no longer reach the unlinked copy.
Delete a Library Panel
Grafana blocks deletion while any dashboard still uses the panel. Unlink the panel on each dashboard, or remove it from them, and the delete button works. This rule prevents broken dashboards.
Library Panels and Variables
A library panel can use dashboard variables in its query. The panel adapts to whichever dashboard shows it, as long as that dashboard defines a variable with the same name. Agree on names such as $instance and $env across your team so shared panels keep working.
Permissions
Library panels live in folders and follow folder permissions. Editors of the folder can change the panel. Viewers of a dashboard see the panel but cannot change it. Store shared panels in a folder that only trusted editors can change, since each edit reaches many dashboards.
Good Habits
- Use descriptive names that include the service and the metric.
- Keep library panels in a dedicated folder, such as Shared Panels.
- Announce major changes to the teams who depend on the panel.
- Remove unused panels every few months.