{"id":19608776,"url":"https://github.com/etsy/rules_grafana","last_synced_at":"2025-10-20T00:16:21.852Z","repository":{"id":33888318,"uuid":"149487632","full_name":"etsy/rules_grafana","owner":"etsy","description":"Bazel rules for building Grafana dashboards","archived":false,"fork":false,"pushed_at":"2024-03-18T19:29:00.000Z","size":52,"stargazers_count":66,"open_issues_count":1,"forks_count":9,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-03-18T21:13:33.420Z","etag":null,"topics":["bazel","bazel-rules","grafana","non-sox"],"latest_commit_sha":null,"homepage":"","language":"Starlark","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-09-19T17:29:27.000Z","updated_at":"2024-04-14T18:25:47.086Z","dependencies_parsed_at":"2024-02-04T11:41:29.609Z","dependency_job_id":"ced2536b-41d4-4fc7-85ca-c330e77b08b0","html_url":"https://github.com/etsy/rules_grafana","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etsy%2Frules_grafana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etsy%2Frules_grafana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etsy%2Frules_grafana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etsy%2Frules_grafana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etsy","download_url":"https://codeload.github.com/etsy/rules_grafana/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251204748,"owners_count":21552282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bazel","bazel-rules","grafana","non-sox"],"created_at":"2024-11-11T10:17:11.788Z","updated_at":"2025-10-20T00:16:21.847Z","avatar_url":"https://github.com/etsy.png","language":"Starlark","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `rules_grafana` for Bazel\n\nDashboards as code, the [Bazel](https://bazel.build/) way.\nWrite Grafana dashboards with Python\nand build them in into a reusable Docker image.\n\nTry it out!  `bazel run //example:grafana` to build and load a Docker image,\nthen run it with `docker run --rm -p 3000:3000 bazel/example:grafana`.\nThen load Grafana in your browser at `http://localhost:3000`!\n\n## Installing\n\nLoad `rules_grafana` by adding the following to your `MODULE.bazel`:\n\n```starlark\nbazel_dep(name = \"rules_grafana\", version = \"1.0.0\")\n\n# For plugins and container setup\ngrafana_ext = use_extension(\"@rules_grafana//grafana:extensions.bzl\", \"grafana\")\nuse_repo(grafana_ext, \"grafana_oci\")\n\n# Optional: Add plugins\ngrafana_ext.plugin(\n    name = \"my_plugin\",\n    urls = [\"https://grafana.com/api/plugins/my-plugin/versions/1.0.0/download\"],\n    sha256 = \"...\",\n    type = \"zip\",\n)\nuse_repo(grafana_ext, \"my_plugin\")\n```\n\n`rules_grafana` depends on [`rules_python`](https://github.com/bazelbuild/rules_python) and\n[`rules_oci`](https://github.com/bazel-contrib/rules_oci), but these are automatically managed\nthrough Bazel's module system.\n\n## Bazel compatibility\n\nRequires Bazel 7.0.0 or later with bzlmod enabled.\n\n## Usage\n\n`rules_grafana` makes it easy to build dashboards and incorporate them into your Bazel build,\nand to build a complete, runnable Docker image.\n\nDashboards can be either hard-coded JSON files or Python scripts that generate dashboards.\n\n### JSON dashboards\n\nUse `json_dashboards` to add JSON files containing dashboard to your build.\nThe JSON must be a complete, valid Grafana dashboard;\nsee the [Grafana docs](http://docs.grafana.org/reference/dashboard/) for details on the JSON format.\n\n```python\nload(\"@rules_grafana//grafana:grafana.bzl\", \"json_dashboards\")\n\njson_dashboards(\n    name = \"dashboards\",\n    srcs = [\"awesome_graphs.json\"],\n)\n```\n\nUnlike using the JSON files directly,\n`json_dashboards` will check the syntax of your files\nand ensure that each dashboard has a `uid` set,\nto ensure it has a [consistent URL in Grafana](http://docs.grafana.org/administration/provisioning/#reuseable-dashboard-urls).\n\n### Python dashboards\n\nDashboards can also be generated with Python,\nusing the [`grafanalib`](https://github.com/weaveworks/grafanalib) library.\n`grafanalib` is automatically imported,\nand you can also add other `deps` to help build your dashboard.\n\nEach Python dashboard file should print the complete JSON of a Grafana dashboard.\nAn easy way to do that is to follow a template like this:\n\n```python\nfrom grafanalib.core import *\nfrom grafanalib._gen import print_dashboard\n\ndashboard = Dashboard(\n    # Fill in your dashboard!\n)\n\nprint_dashboard(dashboard.auto_panel_ids()) # `auto_panel_ids()` call is required!\n```\n\nUse `py_dashboards` to add Python files that generate dashboards to your build.\n\n```python\nload(\"@rules_grafana//grafana:grafana.bzl\", \"py_dashboards\")\n\npy_dashboards(\n    name = \"dashboards\",\n    srcs = [\"amazing_graphs.py\", \"even_better_graphs.py\"],\n)\n```\n\nYou can run the Python and see the generated JSON with the `FOO_builder` target created by `py_dashboards`,\nwhere `FOO` is the Python filename without `.py`.\nFor example, run `bazel run //example:sample_builder` in this repository to see the output of `sample.py`.\nThe JSON is generated at build time, not a run time, so Python isn't a runtime dependency.\n\n### Docker image\n\nUse `grafana_image` to build your dashboards into a Docker image containing Grafana.\nWhen you run the image, it starts Grafana on port 3000\nand serves all of the dashboards you've built,\ndirectly from the container.\n\nThe dashboards and datasources are added via [Grafana provisioning](http://docs.grafana.org/administration/provisioning/),\nwhere the configuration and sources are declared and built into the image,\nalongside all the dashboards.\nYou must provide a `datasources.yaml` file declaring your datasources;\nsee the [Grafana datasources docs](http://docs.grafana.org/administration/provisioning/#datasources) for details of the format.\n\nGrafana plugins can be installed into the image too.\nUse the `grafana` module extension to download plugins:\n\n```starlark\n# In your MODULE.bazel\ngrafana_ext = use_extension(\"@rules_grafana//grafana:extensions.bzl\", \"grafana\")\ngrafana_ext.plugin(\n    name = \"grafana_plotly_plugin\",\n    urls = [\"https://grafana.com/api/plugins/natel-plotly-panel/versions/0.0.7/download\"],\n    sha256 = \"818ab33b42a1421b561f4e44f0cd19cd1a56767d3952045b8042a4da58bd470e\",\n    type = \"zip\",\n)\nuse_repo(grafana_ext, \"grafana_plotly_plugin\")\n```\n\nThen pass the plugin to the image rule's `plugins` list as `@grafana_plotly_plugin//:plugin`.\n\n### Custom grafana image\n\nThe default version of Grafana (12.0) may not suit your needs.\nYou can override the container by modifying the grafana extension in your MODULE.bazel.\n\n## API reference\n\n### `json_dashboards`\n\nProcesses a set of `.json` Grafana dashboards for inclusion in the image.\n\nArguments:\n\n- `name`: Unique name for this target.  Required.\n- `srcs`: List of labels of `.json` files to build into dashboards.  Required.\n\n### `py_dashboards`\n\nProcesses a set of `.py` Grafana dashboards for inclusion in the image.\n\nArguments:\n\n- `name`: Unique name for this target.  Required.\n- `srcs`: List of labels of `.py` files to build into dashboards.  Required.\n- `deps`: List of labels of additional `py_library` targets to use while executing the Python dashboards.  Optional, default `[]`.\n\n### `grafana_image`\n\nBuilds a Docker image containing Grafana and the provided dashboards and datasources.\n\nArguments:\n\n- `name`: Unique name for this target.  Required.\n- `dashboards`: List of labels of `json_dashboards` and/or `py_dashboards` targets to include in the image.  Required.\n- `datasources`: List of labels of `datasources.yaml` files to include in the image ([Grafana datasources docs](http://docs.grafana.org/administration/provisioning/#datasources)).  Required.\n- `plugins`: List of labels of plugin targets from the grafana extension, like `@your_plugin_name//:plugin`.  Optional.\n- `env`: Dictionary of environment variant names to values, set in the Docker image when Grafana is run.  Optional.\n    Useful for setting runtime configs with `GF_` variables.\n\n### Module extension: `grafana`\n\nModule extension for managing Grafana plugins and container configuration.\n\n#### `grafana.plugin`\n\nDownloads a Grafana plugin for inclusion in a `grafana_image`.\n\nArguments:\n\n- `name`: Unique name for this plugin repository.  Required.\n- `urls`: List of strings of mirror URLs referencing the plugin archive.  Required.\n- `sha256`: String of the expected SHA-256 hash of the download.  Required.\n- `type`: The archive type of the downloaded file as a string;\n          takes the same values as the `type` attribute of Bazel's `http_archive` rule.\n          Optional, as the archive type can be determined from the plugin's file extension.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetsy%2Frules_grafana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetsy%2Frules_grafana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetsy%2Frules_grafana/lists"}