GitLocker: The Coding Marketplace

Description:

grafanaclient 4.1.0

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

Or using asynchronous code... the interfaces are identical except for the fact that you will handle coroutines (async/await).
from grafana_client import AsyncGrafanaApi
import asyncio

async def main():
# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = AsyncGrafanaApi.from_url("https://username:password@daq.example.org/grafana/")

# Create user
user = await grafana.admin.create_user({
"name": "User",
"email": "user@example.org",
"login": "user",
"password": "userpassword",
"OrgId": 1,
})

# Change user password
user = await grafana.admin.change_user_password(2, "newpassword")

asyncio.run(main())

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 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:password@daq.example.org/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:password@daq.example.org/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 niquests.auth.AuthBase instance.
Selecting Organizations
If the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication),
it will use the user's current organization context.
That context can be changed with the GrafanaApi.user.switch_actual_user_organisation function.
grafana.user.switch_actual_user_organisation(1)

An instance of GrafanaApi can also be bound to a single organization with the organization_id parameter,
ensuring that all requests will be made to that organization.
This parameter will cause GrafanaClient to use the X-Grafana-Org-Id header.
grafana = GrafanaApi(..., organization_id=1)

API Tokens are bound to a single organization, so the organization_id parameter does not need to be specified.
Timeout settings
The default timeout value is five seconds, used for both connect and read timeout.
The constructors of GrafanaApi and GrafanaClient, as well as the factory methods
from_url and from_env accept the timeout argument, which can be obtained as a
scalar float value, or as a tuple of (<read timeout>, <connect timeout>).
Proxy
The underlying niquests 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

DNS Resolver
niquests support using a custom DNS resolver, like but not limited, DNS-over-HTTPS, and DNS-over-QUIC.
You will have to set NIQUESTS_DNS_URL environment variable. For example:
export NIQUESTS_DNS_URL="doh+cloudflare://"

See the documentation to learn
more about accepted URL parameters and protocols.
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-10.x. However, earlier
versions of Grafana might not support certain features or subsystems.
Overview

API
Status

Admin
+

Alerting
+-

Alerting Notification Channels
+

Alerting Provisioning
+

Annotations
+

Authentication
+-

Dashboard
+

Dashboard Versions
+

Dashboard Permissions
+

Data Source
+

Data Source Permissions
+

External Group Sync
+

Folder
+

Folder Permissions
+

Folder/Dashboard Search
+-

Health
+

Library Elements
+

Organisation
+

Other
+

Plugin
+

Preferences
+

Rbac
+-

Snapshot
+

Teams
+

User
+

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

Project information
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 set up a development environment for grafana-client, please
follow the development documentation.
License
grafana-client is licensed under the terms of the MIT License, see LICENSE file.