# grafana-dashboard-python
Write Grafana dashboards in Python, without losing thousands of dashboards in the zoo
## Introduction
Grafana's [official best practice](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/best-practices/#high---optimized-use) recommends **using scripts to generate dashboards**, instead of creating it in GUI manually. This avoids a lot of repetition, and also ensures consistency.
[Grafanalib](https://github.com/weaveworks/grafanalib) is a library for that purpose, and I have enjoyed it in my system. However, I also want to **use (download and customize) the dashboards already built by other people** (https://grafana.com/grafana/dashboards/). Therefore, I create this small tool.
## Sample workflow 1: Customize an existing dashboard
### Step 1: Convert standard Grafana dashboard into Python code
To begin with, get your dashboard from wherever you like, such as https://grafana.com/grafana/dashboards/, or your legacy dashboards. Then convert it to Python code:
```py
grafana_dashboard json-to-python --json-path ... --python-path ...
```
Currently, you may need a bit of cleanup for the generated code, mostly add a few `import`s. (Should be automated in future releases.)
### Step 2: Customize it in Python
Since it is nothing but normal Python code, you can customize it freely, and it can be easily made consistent with other dashboards written in Python.
For example, I personally have a few annotations that should be applied to every dashboard, then I can just add `annotations=get_common_annotations()` and that's all - no need to copy-and-paste dozens of lines.
### Step 3: Deploy it
Same as Grafanalib, just convert Python into JSON, and use you favorite approach to send the JSON to Grafana. As for the arguments of the conversion command:
```py
grafana_dashboard python-to-json --python-base-dir ... --python-base-package ... --json-dir ...
```
## Sample workflow 2: Create a dashboard from scratch
Just throw away "step 1" in the sample above :)
## Stability / bugs / tests
Firstly, it works well for my own cases, and I have ensured the parts that I use looks correct. However, there are definitely rough edges that I have not manually optimized, since Grafana's auto-generated schema will not solve everything.
As you know, my philosophy is that, if a tool that I use internally may also be useful for others, I will open source it to help people - that's why this tiny utility is on GitHub. However, I am too busy recently, and thus do not have that much time to cover every rough edge of Grafana features that I have not used.
If you see a bug, feel free to create an issue or PR, and I usually reply quickly (within minutes or hours, except sleeping). From my experience, it is very trivial to solve the hard edges. Anyway, this is nothing but **a series of Pydantic models with almost *no logic***. How can it have hard-to-fix bugs? ;)
More importantly, you can always check the output JSON to see whether there is an unexpected output. For example, in my own workflow, I let Git track the JSON. Then, if anything changes, I have a clear diff.
## Examples
Examples can be found at `/examples`.
## Relation with Grafanalib
I do hope that I can simply PR to Grafanalib and add the "convert any JSON into Python" feature. However, in my humble opinion it is quite hard: Grafanalib's API differs a lot from Grafana's JSON API. Therefore, though I can easily convert JSON to Python dict or object constructor, it is time-consuming and error-prone to further convert it into valid Grafanalib code.
## How it works
Pretty simple. When using it, it is nothing but a series of `Pydantic` models, with almost no logic except that. So you are indeed using the serialization and deserialization feature of Pydantic.
As for how the Pydantic code is created: It is generated automatically from Grafana's official [schema](https://github.com/grafana/grok), and then manually tweaked for a better developer experience (e.g. provide more sensible defaults, make types looser). All changes are recorded in a patch file, so the package can be easily upgraded when Grafana upgrades, and always keep the definition accurate.
## Tips
* You can (auto) migrate the JSON to latest `schemaVersion` by importing the JSON into Grafana and download/save JSON from the imported dashboard. Doing so may make your code a bit cleaner.
* If the Python generated from JSON gives weird results, it is trivial to debug: Just compare the newly generated JSON with the original JSON, and fix any noticeable differences.
Raw data
{
"_id": null,
"home_page": "https://github.com/fzyzcjy/grafana-dashboard-python",
"name": "grafana-dashboard",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "grafana dashboard json",
"author": "fzyzcjy",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/3d/ec/e148aad8c18e38f932abd0c152f4c0a8dec5a7f26bb4050a1ee6e4e94776/grafana_dashboard-0.1.1.tar.gz",
"platform": null,
"description": "# grafana-dashboard-python\n\nWrite Grafana dashboards in Python, without losing thousands of dashboards in the zoo\n\n## Introduction\n\nGrafana's [official best practice](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/best-practices/#high---optimized-use) recommends **using scripts to generate dashboards**, instead of creating it in GUI manually. This avoids a lot of repetition, and also ensures consistency.\n\n[Grafanalib](https://github.com/weaveworks/grafanalib) is a library for that purpose, and I have enjoyed it in my system. However, I also want to **use (download and customize) the dashboards already built by other people** (https://grafana.com/grafana/dashboards/). Therefore, I create this small tool.\n\n## Sample workflow 1: Customize an existing dashboard\n\n### Step 1: Convert standard Grafana dashboard into Python code\n\nTo begin with, get your dashboard from wherever you like, such as https://grafana.com/grafana/dashboards/, or your legacy dashboards. Then convert it to Python code:\n\n```py\ngrafana_dashboard json-to-python --json-path ... --python-path ...\n```\n\nCurrently, you may need a bit of cleanup for the generated code, mostly add a few `import`s. (Should be automated in future releases.)\n\n### Step 2: Customize it in Python\n\nSince it is nothing but normal Python code, you can customize it freely, and it can be easily made consistent with other dashboards written in Python.\n\nFor example, I personally have a few annotations that should be applied to every dashboard, then I can just add `annotations=get_common_annotations()` and that's all - no need to copy-and-paste dozens of lines.\n\n### Step 3: Deploy it\n\nSame as Grafanalib, just convert Python into JSON, and use you favorite approach to send the JSON to Grafana. As for the arguments of the conversion command:\n\n```py\ngrafana_dashboard python-to-json --python-base-dir ... --python-base-package ... --json-dir ...\n```\n\n## Sample workflow 2: Create a dashboard from scratch\n\nJust throw away \"step 1\" in the sample above :)\n\n## Stability / bugs / tests\n\nFirstly, it works well for my own cases, and I have ensured the parts that I use looks correct. However, there are definitely rough edges that I have not manually optimized, since Grafana's auto-generated schema will not solve everything.\n\nAs you know, my philosophy is that, if a tool that I use internally may also be useful for others, I will open source it to help people - that's why this tiny utility is on GitHub. However, I am too busy recently, and thus do not have that much time to cover every rough edge of Grafana features that I have not used.\n\nIf you see a bug, feel free to create an issue or PR, and I usually reply quickly (within minutes or hours, except sleeping). From my experience, it is very trivial to solve the hard edges. Anyway, this is nothing but **a series of Pydantic models with almost *no logic***. How can it have hard-to-fix bugs? ;)\n\nMore importantly, you can always check the output JSON to see whether there is an unexpected output. For example, in my own workflow, I let Git track the JSON. Then, if anything changes, I have a clear diff.\n\n## Examples\n\nExamples can be found at `/examples`.\n\n## Relation with Grafanalib\n\nI do hope that I can simply PR to Grafanalib and add the \"convert any JSON into Python\" feature. However, in my humble opinion it is quite hard: Grafanalib's API differs a lot from Grafana's JSON API. Therefore, though I can easily convert JSON to Python dict or object constructor, it is time-consuming and error-prone to further convert it into valid Grafanalib code.\n\n## How it works\n\nPretty simple. When using it, it is nothing but a series of `Pydantic` models, with almost no logic except that. So you are indeed using the serialization and deserialization feature of Pydantic.\n\nAs for how the Pydantic code is created: It is generated automatically from Grafana's official [schema](https://github.com/grafana/grok), and then manually tweaked for a better developer experience (e.g. provide more sensible defaults, make types looser). All changes are recorded in a patch file, so the package can be easily upgraded when Grafana upgrades, and always keep the definition accurate.\n\n## Tips\n\n* You can (auto) migrate the JSON to latest `schemaVersion` by importing the JSON into Grafana and download/save JSON from the imported dashboard. Doing so may make your code a bit cleaner.\n* If the Python generated from JSON gives weird results, it is trivial to debug: Just compare the newly generated JSON with the original JSON, and fix any noticeable differences.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Write Grafana dashboards in Python, without losing thousands of dashboards in the zoo",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/fzyzcjy/grafana-dashboard-python"
},
"split_keywords": [
"grafana",
"dashboard",
"json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bee7debbed2d7a576025610ef70349b2268bdddb05f7dc75e9359b347b4b077c",
"md5": "7e0e74d2cac603afb5f350e5e880e676",
"sha256": "eb0065cebc5cb82fc54f9f983259eca446a01837cae22bd93b9d504de6034991"
},
"downloads": -1,
"filename": "grafana_dashboard-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e0e74d2cac603afb5f350e5e880e676",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 63029,
"upload_time": "2023-07-12T01:20:31",
"upload_time_iso_8601": "2023-07-12T01:20:31.131644Z",
"url": "https://files.pythonhosted.org/packages/be/e7/debbed2d7a576025610ef70349b2268bdddb05f7dc75e9359b347b4b077c/grafana_dashboard-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3dece148aad8c18e38f932abd0c152f4c0a8dec5a7f26bb4050a1ee6e4e94776",
"md5": "1a4b7b621e3472c203d3b433a51b3ddb",
"sha256": "57a2e62c89f3a300c8165d20637095a90d9a9027b0a6d2ffcbc4fbeafbb19a37"
},
"downloads": -1,
"filename": "grafana_dashboard-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1a4b7b621e3472c203d3b433a51b3ddb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 38918,
"upload_time": "2023-07-12T01:20:33",
"upload_time_iso_8601": "2023-07-12T01:20:33.190044Z",
"url": "https://files.pythonhosted.org/packages/3d/ec/e148aad8c18e38f932abd0c152f4c0a8dec5a7f26bb4050a1ee6e4e94776/grafana_dashboard-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-12 01:20:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fzyzcjy",
"github_project": "grafana-dashboard-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "grafana-dashboard"
}
JSON
