Usage

Most modules will depend on a GrafanaApi instance.

from grafana_client import GrafanaApi

gfn = GrafanaApi(
                auth=(
                        os.getenv("GF_SECURITY_ADMIN_USER"),
                        os.getenv("GF_SECURITY_ADMIN_PASSWORD")
                ),
                port=os.getenv("GF_SERVER_HTTP_PORT"),
        )

Finding Things

grafanarmadillo can be used to find your things in Grafana, such as alerts and dashboards and folders.

from grafanarmadillo.find import Finder

# inject the GrafanaApi
finder = Finder(gfn)

# get all dashboards named "important_dashboard"
finder.find_dashboards("important_dashboard")

# get a dashboard by its name and folder
finder.get_dashboard("Folder", "Dashboard")

# get a dashboard by its path
finder.get_from_path("/Folder/Dashboard")

# get an alert by its folder and name
finder.get_alert("Folder", "Alert")

Importing and Exporting

grafanarmadillo can be used to import and export Grafana dashboards. It works well with the Finder.

import json

from grafanarmadillo.dashboarder import Dashboarder
from grafanarmadillo.find import Finder


def export_dashboard(gfn, dashboard_path, destination_file):
	finder, dashboarder = Finder(gfn), Dashboarder(gfn)

	# start by getting the name of the dashboard
	dashboard_info = finder.get_from_path(dashboard_path)

	# export a dashboard. You could save this into a file and commit that to git
	exported_dashboard, _exported_folder = dashboarder.export_dashboard(dashboard_info)

	return destination_file.write(json.dumps(exported_dashboard))


def import_dashboard(gfn, folder, source_file):
	dashboarder = Dashboarder(gfn)

	dashboard = json.loads(source_file.read())

	# you could then load that dashboard from a file and import it into Grafana
	return dashboarder.import_dashboard(dashboard, folder)


def clone_dashboard_contents(gfn, source_path, dest_path):
	finder, dashboarder = Finder(gfn), Dashboarder(gfn)

	# you can also "clone" the contents of a Grafana dashboard
	# which is useful for propagating a template to other dashboards
	template_info = finder.get_from_path(source_path)
	content = dashboarder.get_dashboard_content(template_info)

	prod_dashboard_info = finder.get_from_path(dest_path)
	return dashboarder.set_dashboard_content(prod_dashboard_info, content)

grafanarmadillo can similarly be used to import and export Grafana alerts.

import json

from grafana_client import GrafanaApi

from grafanarmadillo.alerter import Alerter
from grafanarmadillo.find import Finder


def export_alert(gfn: GrafanaApi, alert_folder, alert_name, destination_file):
	finder, alerter = Finder(gfn), Alerter(gfn)

	# find the alert info
	alert_info = finder.get_alert(alert_folder, alert_name)

	# export the alert. You could save this into a file and commit that to git
	exported_alert, _exported_folder = alerter.export_alert(alert_info)

	destination_file.write(json.dumps(exported_alert))


def import_alert(gfn: GrafanaApi, folder, template):
	alerter = Alerter(gfn)

	alert = template
	alerter.import_alert(alert, folder)

Templating

grafanarmadillo makes it easier to transform dashboards into templates and templates into dashboards.

from typing import List

from grafana_client import GrafanaApi

from grafanarmadillo.dashboarder import Dashboarder
from grafanarmadillo.find import Finder
from grafanarmadillo.templator import Templator, findreplace
from grafanarmadillo.types import DashboardContent


def template_for_clients(gfn: GrafanaApi, service_name: str, clients: List[str]):
	"""Pull a template for a service from the Templates folder on Grafana and fills it out for a client."""
	finder, dashboarder, templator = Finder(gfn), Dashboarder(gfn), Templator()

	dashboard_info = finder.get_dashboard("Templates", service_name)
	exported_dashboard = dashboarder.get_dashboard_content(dashboard_info)

	template = templator.make_template_from_dashboard(exported_dashboard)

	for client in clients:
		folder = dashboarder.api.folder.create_folder(client)
		info = DashboardContent({"title": f"{service_name}"})

		dashboard = templator.make_dashboard_from_template(info, template)

		dashboarder.import_dashboard(dashboard, folder)


# It's easy to do a global findreplace throughout all strings in a dashboard with the `findreplace` helper
# This example templates the ID of the deployment, the environment, and the version

template_maker = Templator(
	make_template=findreplace(
		{
			"0000": "$deployment_id",
			"test": "$env",
			"1.0.0": "$version",
			"ThingDoer": "$service",
		}
	)
)

# We can then expand the template with values later

dashboard_maker = Templator(
	fill_template=findreplace(
		{"$deployment_id": "1337", "$env": "prod", "$version": "1.4.5", "$service": "ETL"}
	)
)