grafana-client

About

A client library for accessing the Grafana HTTP API, written in Python.

Setup

Install the package from PyPI.

pip install grafana-client --upgrade

Usage

API overview

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:password@daq.example.org/grafana/")

# Create user
user = grafana.admin.create_user({
    "name": "User", 
    "email": "user@example.org", 
    "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("test@example.org")

# 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"})

Example programs

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.

Authentication

There are two ways to authenticate to the Grafana API. Either use an API token, or HTTP basic auth.

To use the admin API, you need to use HTTP Basic Authentication, as stated at the Grafana Admin API documentation.

from grafana_client import GrafanaApi

# Use Grafana API token.
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
    credential="eyJrIjoiWHg...dGJpZCI6MX0=",
)

# Use HTTP basic authentication.
grafana = GrafanaApi.from_url(
    url="https://username:password@daq.example.org/grafana/",
)
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
    credential=("username", "password")
)

# Optionally turn off TLS certificate verification.
grafana = GrafanaApi.from_url(
    url="https://username:password@daq.example.org/grafana/?verify=false",
)

# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.
grafana = GrafanaApi.from_env()

Proxy

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

Details

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.

Compatibility

grafana-client is largely compatible with Grafana 5.x-9.x. However, earlier versions of Grafana might not support certain features or subsystems.

Overview

Data source health check

Introduction

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.

Compatibility

The minimum required version for data source health checks is Grafana 7. Prometheus only works on Grafana 8 and newer.

Data source coverage

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.

Applications

A list of applications based on grafana-client.

• grafana-import-tool
• grafana-ldap-sync-script
• grafana-snapshots-tool
• grafana-wtf
• nixops-grafana

History

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.

Acknowledgements

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.

Contributing

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

Development

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]
python -m unittest -vvv

License

grafana-client is licensed under the terms of the MIT License, see LICENSE file.