grafana-dashboard-builder is an open-source tool for easier creation of Grafana dashboards. It is written in Python and uses YAML descriptors for dashboard templates.
This project has been inspired by Jenkins Job Builder that allows users to describe Jenkins jobs with human-readable format. grafana-dashboard-builder aims to provide similar simplicity to Grafana dashboard creation and to give users easy way how they can create dashboard templates filled with different configuration.
To install:
pip install grafana-dashboard-builder
or
python setup.py install
An alternative to installing it into the global site-packages is to add it to your user local directory (usually ~/.local).
pip install --user grafana-dashboard-builder
After installation you'll find grafana-dashboard-builder on your path. Help can be printed by --help command-line
option.
usage: grafana-dashboard-builder [-h] -p PATH [PATH ...] [--project PROJECT] [-o OUT] [-c CONFIG]
[--context CONTEXT] [--plugins PLUGINS [PLUGINS ...]]
[--exporter EXPORTERS [EXPORTERS ...]]
optional arguments:
-h, --help show this help message and exit
-p PATH [PATH ...], --path PATH [PATH ...]
List of path to YAML definition files
--project PROJECT (deprecated, use path) Location of the file containing
project definition.
-o OUT, --out OUT (deprecated, use config file and file exporter) Path
to output folder
-c CONFIG, --config CONFIG
Configuration file containing fine-tuned setup of
builder's components.
--context CONTEXT YAML structure defining parameters for dashboard
definition. Effectively overrides any parameter
defined on project level.
--plugins PLUGINS [PLUGINS ...]
List of external component plugins to load
--exporter EXPORTERS [EXPORTERS ...]
List of dashboard exporters
To start you need to create project configuration that needs to be in one YAML document. And some examples with current can be found in sample project:
grafana-dashboard-builder -p ./samples/project.yaml --exporter file --config ./samples/config.yamlgrafana-dashboard-builder provides several builtin exporters that can be enabled through --exporter option.
Configuration for all of them is to be provided in configuration file given in --config option. Look at
sample config.
File exporter is used when you want to store dashboards as JSON files on your local disk.
file:
output_folder: /some/directory/on/my/diskTo use file exporter run grafana-dashboard-builder with --exporter file option.
grafana-dashboard-builder currently supports persisting dashboards to Elastic Search used by Grafana prior to version 2.0
To configure Elastic Search endpoint put following structure to your configuration file:
elastic-search:
host: https://this-is-my-domain.com
password: my_password
username: my_usernameWith this configuration your dashboard will be uploaded to https://this-is-my-domain.com/es/grafana-dash/dashboard/dashboard_name
If you do not want to store your credentials in the configuration file you can use environment variables ES_PASSWORD
and ES_USERNAME.
To use elastic search exporter run grafana-dashboard-builder with --exporter elastic-search option.
grafana-dashboard-builder currently supports Grafana version 2.0 API.
To configure Grafana endpoint put following structure to your configuration file:
grafana:
host: https://this-is-my-domain.com
password: my_password
username: my_usernameWith this configuration your dashboard will be POSTed to https://this-is-my-domain.com/api/dashboards/db
If you do not want to store your credentials in the configuration file you can use environment variables
GRAFANA_PASSWORD and GRAFANA_USERNAME.
You can use Organization API Key to access Grafana API:
Set token in your configuration file:
grafana:
host: https://this-is-my-domain.com
token: eyJrIjoiOGNTW...o2b2123kO==Or in GRAFANA_TOKEN environment variable.
Read more about authentication in Grafana docs.
To use Grafana exporter run grafana-dashboard-builder with --exporter grafana option.
At this moment grafana-dashboard-builder supports following data stores:
Each component follows the same configuration format. Top level must contain 2 fields - name and component type. Under component type is wrapped definition of the component.
- name: some-name
component-type:
component-param1: param-value
component-param2: other-valueComponents can be defined in multiple source files that are passed through --path option. If a path is directory
it is recursively walked and all files are processed.
Components define basic building blocks such as rows, graphs and template queries. They can be defined in-place or be named and reused within other components and dashboards.
Components can define parameters that can be passed from parent component to its children.
- name: graph-name
panels:
- graph:
target: target
y_formats: [bytes, short]
span: 4- name: row-name
rows:
- row:
title: Placeholder row
panels:
- graph-name
- graph:
target: target
y_formats: [bytes, short]
span: 4Another component is template queries that allow you to define just one query string for hierarchical variables. Each query part that starts with $ sign will appear as one variable.
- name: template-name
templates:
- query:
query: '{metric-prefix}.$component.$application'Dashboard is top-level object composed of several components.
- name: overview
dashboard:
title: overview dashboard
time_options: [1h]
refresh_intervals: [5m]
templates:
- template-name:
metric-prefix: '{metric-prefix}'
time:
from: now-12h
to: now
rows:
- row-nameProject is an entry point for builder and defines which dashboards will be generated and provides parameters to them.
- name: Example project
project:
dashboard-prefix: MyApp
metric-prefix: metric.prefix
dashboards:
- overviewThe biggest benefit of grafana-dashboard-builder is that you can generate several dashboards from one dashboard template just by defining multiple values for a parameter that is contained in dashboard name. Following project will generate 2 dashboards named prefix1-dashboard and prefix2-dashboard.
- name: Example project
project:
dashboard-prefix:
- prefix1
- prefix2
dashboards:
- '{dashboard-prefix}-dashboard'Thanks to project component you can use one dashboard template and configure it with different parameters. But what if you need to use different params based on the Grafana you are uploading dashboards to. That's why you can define configuration externally to your projects and dashboard templates.
You can reference configuration stored in YAML with -config option or even inline it to --context option. External
configuration file can look like:
context:
region: eu
default-datacenter: cze
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent