Export and import Grafana dashboards using the Grafana HTTP API and grafana-client.
pip install --upgrade 'grafana-import[builder] @ git+https://github.com/grafana-toolbox/grafana-import.git'
Currently, there is no up-to-date version on PyPI, so we recommend to
install directly from the repository. The command outlined above describes
a full installation of grafana-import
, including support for dashboard
builders, aka. dashboard-as-code.
You can use grafana-import
in ad hoc mode without a configuration file.
In order to do some orientation flights, start a Grafana instance using Podman or Docker.
docker run --rm -it --name=grafana --publish=3000:3000 \
--env='GF_SECURITY_ADMIN_PASSWORD=admin' grafana/grafana:latest
If you don't have any Grafana dashboard representations at hand, you can
acquire some from the examples
directory within the grafana-import
repository, like this.
wget https://github.com/grafana-toolbox/grafana-snippets/raw/main/dashboard/native-play-influxdb.json
wget https://github.com/grafana-toolbox/grafana-snippets/raw/main/dashboard/gd-prometheus.py
Define Grafana endpoint.
export GRAFANA_URL=http://admin:admin@localhost:3000
Import a dashboard from a JSON file.
grafana-import import -i native-play-influxdb.json
Import a dashboard emitted by a dashboard builder, overwriting it when a dashboard with the same name already exists in the same folder.
grafana-import import --overwrite -i gd-prometheus.py
Watch the input dashboard for changes on disk, and re-upload it, when changed.
grafana-import import --overwrite --reload -i gd-prometheus.py
Export the dashboard titled my-first-dashboard
to the default export directory.
grafana-import export --pretty -d "my-first-dashboard"
Delete the dashboard titled my-first-dashboard
from folder Applications
.
grafana-import remove -f Applications -d "my-first-dashboard"
You can also use grafana-import
with a configuration file. In this way, you
can manage and use different Grafana connection profiles, and also use presets
for application-wide configuration settings.
The configuration is stored in a YAML file. In order to use it optimally, build a directory structure like this:
grafana-import/
- conf/grafana-import.yml
Path to your main configuration file.
- exports/
Path where exported dashboards will be stored.
- imports/
Path where dashboards are imported from.
Then, enter into your directory, and type in your commands.
The configuration file uses two sections, general
, and grafana
.
general
sectionConfigure program directories.
grafana
sectionGrafana authentication settings. You can define multiple Grafana access
configuration sections using different settings for api_key
or Grafana
server URL.
default
In order to connect to Grafana, you can use either vanilla credentials
(username/password), or an authentication token. Because grafana-import
uses grafana-client
, the same features for defining authentication
settings can be used. See also grafana-client authentication variants.
Vanilla credentials can be embedded into the Grafana URL, to be supplied
using the --grafana_url
command line argument, or the GRAFANA_URL
environment variable. For specifying a Grafana authentication token without
using a configuration file, use the GRAFANA_TOKEN
environment variable.
grafana-import provides support for dashboard-as-code builders.
To get inspired what you can do, by reading more examples, please also visit grafonnet examples, grafana-dashboard examples, and grafanalib examples.
Grafonnet is a Jsonnet library for generating Grafana dashboards.
The library is generated from JSON Schemas generated by Grok. In turn, these schemas are generated directly from the Grafana repository, in order to ensure Grafonnet is always synchronized with the development of Grafana without much friction.
Install Jsonnet, and its jsonnet-bundler package manager.
brew install go-jsonnet jsonnet-bundler
Install Grafonnet into a Jsonnet project.
git clone https://github.com/grafana-toolbox/grafana-snippets
cd grafana-snippets/dashboard/grafonnet-simple
jb install github.com/grafana/grafonnet/gen/grafonnet-latest@main
Render dashboard defined in Grafonnet/Jsonnet.
grafana-import import --overwrite -i /path/to/faro.jsonnet
Render dashboard defined using grafana-dashboard.
grafana-import import --overwrite -i /path/to/gd-dashboard.py
Render dashboard defined using grafanalib.
grafana-import import --overwrite -i /path/to/gl-dashboard.py
grafana-import --help
usage: grafana-import [-h] [-a] [-b BASE_PATH] [-c CONFIG_FILE]
[-d DASHBOARD_NAME] [-g GRAFANA_LABEL]
[-f GRAFANA_FOLDER] [-i DASHBOARD_FILE] [-o] [-p] [-v]
[-V]
[ACTION]
play with grafana dashboards json files.
positional arguments:
ACTION action to perform. Is one of 'export', 'import'
(default), or 'remove'.
export: lookup for dashboard name in Grafana and dump
it to local file.
import: import a local dashboard file (previously
exported) to Grafana.
remove: lookup for dashboard name in Grafana and remove
it from Grafana server.
optional arguments:
-h, --help show this help message and exit
-a, --allow_new if a dashboard with same name exists in an another
folder, allow to create a new dashboard with same name
it that folder.
-b BASE_PATH, --base_path BASE_PATH
set base directory to find default files.
-c CONFIG_FILE, --config_file CONFIG_FILE
path to config files.
-d DASHBOARD_NAME, --dashboard_name DASHBOARD_NAME
name of dashboard to export.
-u GRAFANA_URL, --grafana_url GRAFANA_URL
Grafana URL to connect to.
-g GRAFANA_LABEL, --grafana_label GRAFANA_LABEL
label in the config file that represents the grafana to
connect to.
-f GRAFANA_FOLDER, --grafana_folder GRAFANA_FOLDER
the folder name where to import into Grafana.
-i DASHBOARD_FILE, --dashboard_file DASHBOARD_FILE
path to the dashboard file to import into Grafana.
-o, --overwrite if a dashboard with same name exists in folder,
overwrite it with this new one.
-r, --reload Watch the input dashboard for changes on disk, and
re-upload it, when changed.
-p, --pretty use JSON indentation when exporting or extraction of
dashboards.
-v, --verbose verbose mode; display log message to stdout.
-V, --version display program version and exit.
Contributions are welcome, and they are greatly appreciated. You can contribute in many ways, and credit will always be given.
For learning more how to contribute, see the contribution guidelines and learn how to set up a development sandbox.