Grafanalib

0.7.1 · active · verified Thu Apr 16

Grafanalib is a Python library for programmatically building Grafana dashboards. It allows users to define dashboards, panels, and targets in Python code, generating the corresponding Grafana JSON model. As of version 0.7.1, it focuses on adding support for newer Grafana features, with releases occurring periodically to keep up with Grafana updates and dependency bumps.

Common errors

```
HTTP Error 401: Unauthorized
```
cause When attempting to upload a dashboard via Grafana API, the provided API key is invalid or lacks sufficient permissions.

fix Verify that your Grafana API key has 'Editor' or 'Admin' permissions and is correctly configured in your upload script or `grafanalib.client` call. Ensure the API key is not expired.
```
Dashboard import failed: Failed to save dashboard: Invalid JSON: panels[0]: invalid panel type
```
cause You are trying to import a dashboard containing a panel type (e.g., `TimeSeries`, `StateTimeline`, `Pie Chart v2`) that is not supported by your current Grafana server version.

fix Upgrade your Grafana server to a version that supports the specific panel type (e.g., Grafana 8+ for `TimeSeries`). Alternatively, modify your `grafanalib` code to use older, more universally supported panel types like `Graph`.
```
AttributeError: module 'grafanalib' has no attribute 'core'
```
cause Incorrect import pattern. You might be trying to access `grafanalib.core.Dashboard` after `import grafanalib` instead of importing `Dashboard` directly.

fix Use explicit imports: `from grafanalib.core import Dashboard, Graph` etc. Then, refer to `Dashboard()` directly. If you must `import grafanalib`, then you would use `grafanalib.core.Dashboard()` but this is not the idiomatic way.

Warnings

gotcha Grafanalib's generated JSON model compatibility with Grafana server versions: Features like the `TimeSeries` panel (introduced in Grafana v8) will only render correctly if your Grafana instance is compatible (v8+). Deploying a dashboard with newer panel types to an older Grafana server will result in import errors or panels failing to render.
Fix: Ensure your Grafana server version supports the panel types and features used in your `grafanalib` code. Consult Grafana's release notes and `grafanalib`'s changelog for specific feature-version mappings. For older Grafana versions, stick to more established panel types like `Graph`.
gotcha Grafanalib generates JSON; it does not deploy to Grafana automatically. Users often expect direct integration or automatic upload.
Fix: After generating the JSON using `dashboard.to_json_data()`, you must manually import it via the Grafana UI, use the `grafanalib.client` module (which requires a Grafana API key and URL), or write a custom script to POST the JSON to the Grafana API endpoint (`/api/dashboards/db`).
gotcha Hardcoding datasource names can limit dashboard portability. If datasource names change across different Grafana environments (e.g., dev vs. prod), dashboards might break.
Fix: Consider using Grafana's templating features (e.g., `Template.datasource`) or environment variables to dynamically provide datasource names, making your dashboards more flexible and reusable across environments.

Install

pip install grafanalib Install stable version

Imports

Dashboard
```
from grafanalib.core import Dashboard
```
Graph
```
from grafanalib.core import Graph
```
TimeSeries
```
from grafanalib.core import TimeSeries
```
Target
wrong:
```
from grafanalib.core import GraphiteTarget
```
correct:
```
from grafanalib.core import Target
```
GraphiteTarget is a specific implementation of Target; generally, you import the base Target or the specific type you need (e.g., CloudwatchMetricsTarget, InfluxDBTarget).

Quickstart

This quickstart demonstrates how to create a basic Grafana dashboard with a single row and a CPU Usage graph panel. It uses a Prometheus datasource (replace 'my_prometheus_datasource' with your actual datasource name). The output is a JSON string which can be saved and imported into Grafana.

import json
from grafanalib.core import Dashboard, Graph, Row, OPS_FORMAT, SEC_FORMAT, YAxes, YAxis

dashboard = Dashboard(
    title="My First Grafana Dashboard",
    description="A simple dashboard created with grafanalib",
    rows=[
        Row(
            panels=[
                Graph(
                    title="CPU Usage",
                    dataSource='my_prometheus_datasource',
                    targets=[
                        {
                            "expr": 'node_cpu_seconds_total{mode="idle"}',
                            "legendFormat": "idle",
                            "refId": "A"
                        }
                    ],
                    yAxes=YAxes([YAxis(format=OPS_FORMAT), YAxis(format=SEC_FORMAT)]),
                )
            ]
        )
    ],
    id=None
).to_json_data(indent=2)

print(dashboard)

# To upload this dashboard to Grafana:
# 1. Save the output to a file (e.g., my_dashboard.json)
# 2. Use the Grafana UI to import the JSON
# 3. Alternatively, use grafanalib.client or another script to POST to Grafana API

view raw JSON →