Skip to main content

Library for building Grafana dashboards

Project description

==========
grafanalib
==========

.. image:: https://circleci.com/gh/weaveworks/grafanalib.svg?style=shield
:target: https://circleci.com/gh/weaveworks/grafanalib

Do you like `Grafana <http://grafana.org/>`_ but wish you could version your
dashboard configuration? Do you find yourself repeating common patterns? If
so, grafanalib is for you.

grafanalib lets you generate Grafana dashboards from simple Python scripts.

Writing dashboards
==================

The following will configure a dashboard with a single row, with one QPS graph
broken down by status code and another latency graph showing median and 99th
percentile latency:

.. code-block:: python

from grafanalib.core import *


dashboard = Dashboard(
title="Frontend Stats",
rows=[
Row(panels=[
Graph(
title="Frontend QPS",
dataSource='My Prometheus',
targets=[
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"1.."}[1m]))',
legendFormat="1xx",
refId='A',
),
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"2.."}[1m]))',
legendFormat="2xx",
refId='B',
),
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"3.."}[1m]))',
legendFormat="3xx",
refId='C',
),
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"4.."}[1m]))',
legendFormat="4xx",
refId='D',
),
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"5.."}[1m]))',
legendFormat="5xx",
refId='E',
),
],
yAxes=[
YAxis(format=OPS_FORMAT),
YAxis(format=SHORT_FORMAT),
],
alert=Alert(
name="Too many 500s on Nginx",
message="More than 5 QPS of 500s on Nginx for 5 minutes",
alertConditions=[
AlertCondition(
Target(
expr='sum(irate(nginx_http_requests_total{job="default/frontend",status=~"5.."}[1m]))',
legendFormat="5xx",
refId='A',
),
timeRange=TimeRange("5m", "now"),
evaluator=GreaterThan(5),
operator=OP_AND,
reducerType=RTYPE_SUM,
),
],
)
),
Graph(
title="Frontend latency",
dataSource='My Prometheus',
targets=[
Target(
expr='histogram_quantile(0.5, sum(irate(nginx_http_request_duration_seconds_bucket{job="default/frontend"}[1m])) by (le))',
legendFormat="0.5 quantile",
refId='A',
),
Target(
expr='histogram_quantile(0.99, sum(irate(nginx_http_request_duration_seconds_bucket{job="default/frontend"}[1m])) by (le))',
legendFormat="0.99 quantile",
refId='B',
),
],
yAxes=single_y_axis(format=SECONDS_FORMAT),
),
]),
],
).auto_panel_ids()

There is a fair bit of repetition here, but once you figure out what works for
your needs, you can factor that out.
See `our Weave-specific customizations <grafanalib/weave.py>`_ for inspiration.

Generating dashboards
=====================

If you save the above as ``frontend.dashboard.py`` (the suffix must be
``.dashboard.py``), you can then generate the JSON dashboard with:

.. code-block:: console

$ generate-dashboard -o frontend.json frontend.dashboard.py

Installation
============

grafanalib is just a Python package, so:

.. code-block:: console

$ pip install grafanalib

Support
=======

This library is in its very early stages. We'll probably make changes that
break backwards compatibility, although we'll try hard not to.

grafanalib works with Python 2.7, 3.4, 3.5, and 3.6.

Developing
==========
If you're working on the project, and need to build from source, it's done as follows:

.. code-block:: console

$ virtualenv .env
$ . ./.env/bin/activate
$ pip install -e .

`gfdatasource`
==============

This module also provides a script and docker image which can configure grafana
with new sources, or enable app plugins.

The script answers the `--help` with full usage information, but basic
invocation looks like this:

.. code-block:: console

$ <gfdatasource> --grafana-url http://grafana. datasource --data-source-url http://datasource
$ <gfdatasource> --grafana-url http://grafana. app --id my-plugin

Getting Help
============

If you have any questions about, feedback for or problems with ``grafanalib``:

- Invite yourself to the `#weave-community <https://weaveworks.github.io/community-slack/>`_ slack channel.
- Ask a question on the `#weave-community <https://weave-community.slack.com/messages/general/>`_ slack channel.
- Send an email to `weave-users@weave.works <mailto:weave-users@weave.works>`_.
- `File an issue <https://github.com/weaveworks/grafanalib>`_.

Your feedback is always welcome!


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

grafanalib-0.5.2.tar.gz (25.2 kB view details)

Uploaded Source

Built Distributions

grafanalib-0.5.2-py3-none-any.whl (26.6 kB view details)

Uploaded Python 3

grafanalib-0.5.2-py2-none-any.whl (26.6 kB view details)

Uploaded Python 2

File details

Details for the file grafanalib-0.5.2.tar.gz.

File metadata

  • Download URL: grafanalib-0.5.2.tar.gz
  • Upload date:
  • Size: 25.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for grafanalib-0.5.2.tar.gz
Algorithm Hash digest
SHA256 d9ad48a9d555d3d70b47d55ea1c46fbfeaa2fd58a3241341343a4fcbd727e1a1
MD5 1ea7f862d4be37ffdea928cc03416294
BLAKE2b-256 25524c20c918678d4e22bd394b042290384e9cdce6c12454b5c4b98e14b23240

See more details on using hashes here.

File details

Details for the file grafanalib-0.5.2-py3-none-any.whl.

File metadata

File hashes

Hashes for grafanalib-0.5.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f8f8e22a632c58266d524b513d7dcacb6ce97d740816243a05e0db47b74e0ce0
MD5 245b91455fee272ce8bb31381521af14
BLAKE2b-256 ebbee4b9c501574db240f29f79a3f2b51e471dd2001e8e4c27c245d30efa38ca

See more details on using hashes here.

File details

Details for the file grafanalib-0.5.2-py2-none-any.whl.

File metadata

File hashes

Hashes for grafanalib-0.5.2-py2-none-any.whl
Algorithm Hash digest
SHA256 01ce495e3d2f082a14e42c1f2d587b703e2fd0b32d179c482489ebe574a28b6d
MD5 d9c25e9de6897fac887df731b1f5dec4
BLAKE2b-256 67706cbaff28c0d485cf5e659bb3877ea6a3235867747ff69590e453a2bc530b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page