Grafana Dashboards & Templating
Relevant source files
The following files were used as context for generating this wiki page:
The Grafana Dashboards & Templating module is a critical component of the pmm-dump tool, responsible for resolving complex metric selectors from Grafana dashboard definitions. Since pmm-dump aims to export specific metrics from VictoriaMetrics, it must understand how dashboards filter and display data to ensure that all relevant time series are included in the export.
This system interacts with the Grafana API to retrieve dashboard JSON models, parses their internal structures—including panels, rows, and templating variables—and translates them into PromQL-compatible selectors. This allow users to export data by simply specifying a dashboard name rather than manually constructing complex metric queries.
Architecture and Data Flow
The logic for dashboard-based metric resolution flows from the CLI command parsing down to specialized Grafana client requests and expression parsing.
The diagram above shows how a dashboard name provided via the CLI is resolved into VictoriaMetrics selectors.
Sources: cmd/pmm-dump/main.go:210-213, pkg/grafana/grafana.go:27-38
Key Components
| Component | Description |
|---|---|
GetSelectorsFromDashboards | The entry point that iterates through provided dashboard names and collects all unique selectors. |
findDashboardUID | Queries the Grafana Search API (/graph/api/search) to map a human-readable title to a unique identifier (UID). |
getDashboard | Fetches the full JSON model of a dashboard using its UID via the /graph/api/dashboards/uid/ endpoint. |
VMParser | An internal parser (instantiated in pkg/grafana/grafana.go) that traverses panels and templating variables. |
Sources: pkg/grafana/grafana.go:27, pkg/grafana/grafana.go:53, pkg/grafana/grafana.go:76
Dashboard Model Parsing
Dashboards in PMM are stored as complex JSON structures containing multiple layers of information used for data extraction.
Templating Variables
Dashboards use templating blocks to define variables like $node_name, $interval, or $environment. The pmm-dump tool must parse these to understand what values are valid during the export timeframe.
- Query Variables: Variables derived from metric labels (e.g.,
label_values(up, node_name)). - Constant Variables: Fixed values used across the dashboard.
- Interval Variables: Time-range based resolutions (e.g.,
1s, 5s, 1m).
Sources: internal/test/e2e/testdata/dashboards/pmm-home-with-const.json:1330-1530
Panel Target Extraction
Each panel in a dashboard contains targets which house the actual PromQL/MetricsQL expressions. The tool extracts these expressions to determine which metrics are required.
The sequence shows the interaction between the tool and the PMM Server's Grafana instance to resolve selectors.
Sources: pkg/grafana/grafana.go:53-90, cmd/pmm-dump/util.go:340-350
Integration with CLI and Export Logic
Users invoke the dashboard filtering logic using the --dashboard flag. This can be used multiple times to aggregate metrics from various sources.
CLI Usage Example
./pmm-dump export --pmm-url "http://localhost" --dashboard "MySQL Instances Overview" --dashboard "Nodes Overview"
Sources: README.md:105-107
Implementation in Main Loop
In main.go, the application initializes the Grafana client and retrieves selectors before preparing the VictoriaMetrics source:
// From cmd/pmm-dump/main.go
selectors, err := grafana.GetSelectorsFromDashboards(grafanaC, *pmmURL, *dashboards, *instances, startTime, endTime)
if err != nil {
log.Fatal().Msgf("Error retrieving dashboard selectors: %v", err)
}
if *tsSelector != "" {
selectors = append(selectors, *tsSelector)
}
vmSource, ok := prepareVictoriaMetricsSource(grafanaC, *dumpCore, pmmConfig.VictoriaMetricsURL, selectors, *vmNativeData, *vmContentLimit)
Sources: cmd/pmm-dump/main.go:210-221
Dashboard Import and Testing
The project includes an E2E testing suite that validates dashboard interactions. The importCustomDashboards function demonstrates how dashboards are programmatically uploaded to a PMM instance for testing.
| Function | Endpoint | Description |
|---|---|---|
importCustomDashboards | /graph/api/dashboards/import | POSTs a dashboard JSON model to Grafana. |
getAllDashbaordNames | /graph/api/search?query= | Retrieves all available dashboards on the server. |
Sources: internal/test/e2e/dashboard_test.go:73-100, internal/test/e2e/dashboard_test.go:107-120
Test Data Structures
Dashboard JSON files used in testing (e.g., pmm-home-with-const.json) contain:
panels: Array of visualization components.templating: Variable definitions for dynamic filtering.annotations: Event overlays.schemaVersion: Currently supporting version 37.
Sources: internal/test/e2e/testdata/dashboards/pmm-home-with-const.json:1540-1542
Conclusion
The Grafana Dashboards & Templating module enables pmm-dump to act as a "dashboard-aware" export tool. By translating high-level dashboard definitions into granular VictoriaMetrics selectors, it automates the identification of critical troubleshooting data, reducing the manual effort required by engineers to specify export filters.