Package: grafana-client
grafana-clientAboutA client library for accessing the Grafana HTTP API, written in Python.SetupInstall the package from PyPI.pip install grafana-client --upgradeUsageAPI overviewThis section gives you an idea about how to use the API on behalf of a few
samples.fromgrafana_clientimportGrafanaApi# Connect to Grafana API endpoint using the `GrafanaApi` classgrafana=GrafanaApi.from_url("https://username:password@daq.example.org/grafana/")# Create useruser=grafana.admin.create_user({"name":"User","email":"user@example.org","login":"user","password":"userpassword","OrgId":1,})# Change user passworduser=grafana.admin.change_user_password(2,"newpassword")# Search dashboards based on taggrafana.search.search_dashboards(tag="applications")# Find a user by emailuser=grafana.users.find_user("test@example.org")# Add user to team 2grafana.teams.add_team_member(2,user["id"])# Create or update a dashboardgrafana.dashboard.update_dashboard(dashboard={"dashboard":{...},"folderId":0,"overwrite":True})# Delete a dashboard by UIDgrafana.dashboard.delete_dashboard(dashboard_uid="foobar")# Create organizationgrafana.organization.create_organization(organization={"name":"new_organization"})Example programsThere are complete example programs to get you started within theexamples
folderof 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.AuthenticationThere are several ways to authenticate to the Grafana HTTP API.Anonymous accessGrafana API tokenHTTP Basic AuthenticationHTTP Header AuthenticationTheGrafana Admin APIis a subset of the Grafana API. For accessing those API
resources, you will need to use HTTP Basic Authentication.fromgrafana_clientimportGrafanaApi,HeaderAuth,TokenAuth# 1. Anonymous accessgrafana=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 bycredentialcan be an arbitraryrequests.auth.AuthBaseinstance.Selecting OrganizationsIf 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 theGrafanaApi.user.switch_actual_user_organisationfunction.grafana.user.switch_actual_user_organisation(1)An instance ofGrafanaApican also be bound to a single organization with theorganization_idparameter,
ensuring that all requests will be made to that organization.
This parameter will causeGrafanaClientto use theX-Grafana-Org-Id header.grafana=GrafanaApi(...,organization_id=1)API Tokens are bound to a single organization, so theorganization_idparameter does not need to be specified.Timeout settingsThe default timeout value is five seconds, used for both connect and read timeout.The constructors ofGrafanaApiandGrafanaClient, as well as the factory methodsfrom_urlandfrom_envaccept thetimeoutargument, which can be obtained as a
scalarfloatvalue, or as a tuple of(<read timeout>, <connect timeout>).ProxyThe underlyingrequestslibrary honors theHTTP_PROXYandHTTPS_PROXYenvironment variables. Setting them before invoking an application usinggrafana-clienthas been confirmed to work. For example:export HTTP_PROXY=10.10.1.10:3128
export HTTPS_PROXY=10.10.1.11:1080DetailsThis section of the documentation outlines which parts of the Grafana HTTP API
are supported, and to which degree. See alsoGrafana HTTP API reference.Compatibilitygrafana-clientis largely compatible with Grafana 5.x-10.x. However, earlier
versions of Grafana might not support certain features or subsystems.OverviewAPIStatusAdmin+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+Organisation+Other+Plugin+Preferences+Rbac+-Snapshot+Teams+User+Data source health checkIntroductionFor 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 theexamples folderof this repository.CompatibilityThe minimum required version for data source health checks is Grafana 7.
Prometheus only works on Grafana 8 and newer.Data source coverageHealth checks are supported for these Grafana data source types.CrateDBElasticsearchGraphiteInfluxDBJaegerLokiMicrosoft SQL ServerOpenTSDBPostgreSQLPrometheusTempoTestdataZipkinWe are humbly asking the community to contribute adapters for other data
source types, popular or not.ApplicationsA list of applications based ongrafana-client.grafana-import-toolgrafana-ldap-sync-scriptgrafana-snapshots-toolgrafana-wtfnixops-grafanaProject informationHistoryThe library was originally conceived byAndrew Prokhorenkovand contributors
asgrafana_api. Thank you very much for your efforts!Atfuture maintenance ofgrafana_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 tografana-clientand slightly
trimmed the module namespace.AcknowledgementsThanks to the original authors and allcontributorswho helped to co-create
and conceive this software in one way or another. You know who you are.ContributingAny 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/issuesDevelopmentIn order to set up a development environment forgrafana-client, please
follow thedevelopment documentation.Licensegrafana-clientis licensed under the terms of the MIT License, seeLICENSEfile.