A client library for accessing the Grafana HTTP API, written in Python.
Install the package from PyPI.
pip install grafana-client --upgrade
This section gives you an idea about how to use the API on behalf of a few samples.
from grafana_client import GrafanaApi
# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = GrafanaApi.from_url(
"https://username:[email protected]/grafana/")
# Create user
user = grafana.admin.create_user({
"name": "User",
"email": "[email protected]",
"login": "user",
"password": "userpassword",
"OrgId": 1,
})
# Change user password
user = grafana.admin.change_user_password(2, "newpassword")
# Search dashboards based on tag
grafana.search.search_dashboards(tag="applications")
# Find a user by email
user = grafana.users.find_user("[email protected]")
# Add user to team 2
grafana.teams.add_team_member(2, user["id"])
# Create or update a dashboard
grafana.dashboard.update_dashboard(
dashboard={"dashboard": {...}, "folderId": 0, "overwrite": True})
# Delete a dashboard by UID
grafana.dashboard.delete_dashboard(dashboard_uid="foobar")
# Create organization
grafana.organization.create_organization(
organization={"name": "new_organization"})There are complete example programs to get you started within the examples folder of this repository.
Feel free to use them as blueprints for your own programs. If you think your exercises could be useful for others, don't hesitate to share them back.
There are several ways to authenticate to the Grafana HTTP API.
- Anonymous access
- Grafana API token
- HTTP Basic Authentication
- HTTP Header Authentication
The Grafana Admin API is a subset of the Grafana API. For accessing those API resources, you will need to use HTTP Basic Authentication.
from grafana_client import GrafanaApi, HeaderAuth, TokenAuth
# 1. Anonymous access
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
)
# 2. Use Grafana API token.
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=TokenAuth(token="eyJrIjoiWHg...dGJpZCI6MX0="),
)
# 3. Use HTTP basic authentication.
grafana = GrafanaApi.from_url(
url="https://username:[email protected]/grafana/",
)
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=("username", "password")
)
# 4. Use HTTP Header authentication.
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),
)
# Optionally turn off TLS certificate verification.
grafana = GrafanaApi.from_url(
url="https://username:[email protected]/grafana/?verify=false",
)
# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.
grafana = GrafanaApi.from_env()Please note that, on top of the specific examples above, the object obtained by
credential can be an arbitrary requests.auth.AuthBase instance.
The underlying requests library honors the HTTP_PROXY and HTTPS_PROXY
environment variables. Setting them before invoking an application using
grafana-client has been confirmed to work. For example:
export HTTP_PROXY=10.10.1.10:3128
export HTTPS_PROXY=10.10.1.11:1080
This section of the documentation outlines which parts of the Grafana HTTP API are supported, and to which degree. See also Grafana HTTP API reference.
grafana-client is largely compatible with Grafana 5.x-9.x. However, earlier
versions of Grafana might not support certain features or subsystems.
| API | Status |
|---|---|
| Admin | + |
| Alerting | - |
| Alerting Notification Channels | + |
| Annotations | + |
| Authentication | +- |
| Dashboard | + |
| Dashboard Versions | + |
| Dashboard Permissions | + |
| Data Source | + |
| Folder | + |
| Folder Permissions | + |
| Folder/Dashboard Search | +- |
| Health | + |
| Organisation | + |
| Other | + |
| Preferences | + |
| Snapshot | + |
| Teams | + |
| User | + |
For checking whether a Grafana data source is healthy, Grafana 9 and newer has a server-side data source health check API. For earlier versions, a client-side implementation is provided.
This implementation works in the same manner as the "Save & test" button works, when creating a data source in the user interface.
The feature can be explored through corresponding client programs in the examples folder of this repository.
The minimum required version for data source health checks is Grafana 7. Prometheus only works on Grafana 8 and newer.
Health checks are supported for these Grafana data source types.
- CrateDB
- Elasticsearch
- Graphite
- InfluxDB
- Jaeger
- Loki
- Microsoft SQL Server
- OpenTSDB
- PostgreSQL
- Prometheus
- Tempo
- Testdata
- Zipkin
We are humbly asking the community to contribute adapters for other data source types, popular or not.
A list of applications based on grafana-client.
The library was originally conceived by Andrew Prokhorenkov and contributors as grafana_api. Thank you very much for your efforts!
At future maintenance of grafana_api, we discussed the need for a fork
because the repository stopped receiving updates since more than a year.
While forking it, we renamed the package to grafana-client and slightly
trimmed the module namespace.
Thanks to the original authors and all contributors who helped to co-create and conceive this software in one way or another. You know who you are.
Any kind of contribution and feedback are very much welcome! Just create an issue or submit a patch if you think we should include a new feature, or to report or fix a bug.
The issue tracker URL is: https://github.com/panodata/grafana-client/issues
In order to create a development sandbox, you may want to follow this list of commands. When you see the software tests succeed, you should be ready to start hacking.
git clone https://github.com/panodata/grafana-client
cd grafana-client
python3 -m venv .venv
source .venv/bin/activate
pip install --editable=.[test,develop]
poe testgrafana-client is licensed under the terms of the MIT License, see LICENSE file.