GRAFANA WITH SWAMP
Swamp automates a Grafana server through its HTTP API. You create a behavior that points at a Grafana URL, and its methods read and change what that server holds. Each run stores its result as data in your repository.
Get started
curl -fsSL https://swamp-club.com/install.sh | sh swamp repo init swamp extension pull @keeb/grafana swamp extension pull @shrug/grafana-extMost of the work is done by the @keeb/grafana
extension. Its behavior type, @keeb/grafana/instance, takes one required
global argument, grafanaUrl. It also takes an optional apiKey, which you
reference from a vault. The behavior can:
- check that Grafana is running and list its dashboards and datasources
- push a dashboard JSON file from the repository to Grafana, and export a dashboard from Grafana to a JSON file
- fetch a dashboard's full content, including panels and variables
- push alert rules, create or update a Discord webhook contact point, and set the default notification policy
- create annotations, either global or scoped to one dashboard
- query Prometheus metrics and Loki logs through Grafana's datasource proxy
The @shrug/grafana-ext extension adds an admin
behavior type, @shrug/grafana-admin/instance. It signs in to Grafana with
server-admin basic auth and makes sure a service account with a given role
exists in an org. It can also mint a token for that account. Each run is a dry
run unless you pass confirm as true, and a minted token is printed once and
never stored.
To start, the
getting started tutorial
pulls @keeb/grafana into a fresh repository. If you already have a Grafana
behavior, the how-to guides show how to
push a dashboard JSON file, how
to
export a dashboard built in the Grafana UI,
and how to
query metrics and logs.
For how these pieces relate to Swamp's data, vaults and workflows, read
Understanding Grafana automation in Swamp.
The extensions reference lists
every method and its arguments.
Grafana documentation
Getting started with Grafana
Pull the @keeb/grafana extension, create a Grafana instance behavior, validate it, and run discover to list the dashboards and datasources of a Grafana server.
Tutorials →Push a dashboard JSON file to Grafana
Write a dashboard JSON file in the repository and run the pushDashboard method of a @keeb/grafana/instance behavior to create or update it via the Grafana API.
How-to Guides →Export a Grafana dashboard to a JSON file
Run the exportDashboard method of a @keeb/grafana/instance behavior with a dashboard UID to save that Grafana dashboard as a JSON file in your repository.
How-to Guides →Query Prometheus metrics and Loki logs through Grafana
Use the queryMetrics and queryLogs methods of a @keeb/grafana/instance behavior to fetch and store PromQL and LogQL results through Grafana's datasource proxy.
How-to Guides →Grafana extensions
Every Swamp extension for Grafana: behavior types, global arguments, methods, vault configuration and the data each one writes, read from the registry.
Reference →Understanding Grafana automation in Swamp
How the @keeb/grafana and @shrug/grafana-ext extensions map Grafana dashboards, alerts, queries and service accounts onto Swamp data, vaults and workflows.
Explanation →