grafana / dashboard-spec

91 stars 17 forks source link

DEPRECATED: Note, this repo is no-longer under active development. Whilst it was used to render Grafonnet's library for Grafana 7.0, future schema work is happening inside Grafana itself.

THIS REPOSITORY IS NOT BEING MAINTAINED. A SCHEMA IS NOW BEING BUILT DIRECTLY INTO GRAFANA ITSELF.

Grafana Dashboard Spec

Schema description documents for Grafana Dashboard JSON and core panels using the OpenAPI Specification.

Also in this repository is a code generator that uses the schema documents to generate libraries for writing Grafana dashboards as code.

Repo Layout

specs/

Human-managed specification YAML files.

Style Guide for Spec Files

All properties of an object should be defined alphabetically.

All properties should have a description. This is used for API doc generation.

File names should be in camel case. All files referenced as a schema component in a spec.yml should begin with a capital letter (PascalCase). Files containing shared schema components like "gridPos" or "threshold" should be named with a leading underscore.

Each spec directory should have child directories "panels", "targets", "templates" for organizing schema files. All files should live in those directories except "Dashboard.yml" and "spec.yml".

If a property's name could be more descriptive in code or it collides with another name nested in the same object, use the title field to indicate what that object should be called in code. For example, some panels have a top-level array called links and also a nested array called links. The top-level array is referring to panel links while the nested array is referring to data links, therefore, the properties have title set to "Panel Link" and "Data Link". The code generator should use this field instead for deciding method names. Depending on what the language has set for its object inflection property, this will result in methods like, addPanelLink() and addDataLink().

templates/

Templates for the code generator. Child directories are named after the language they contain templates for.

Each language must implement the following templates:

templates/docs.tmpl is an exception because it is language agnostic. All languages use this template for documentation generation.

Style Guide for Templates

Object arrays should have "appender" methods. For example addLink() and addTarget().

Objects nested one level should have "setter" methods with all simple fields as arguments. For example, setGridPos() and setLegend().

If fields need special processing, set them as readOnly and implement static methods for setting them. For example if you need to add an incrementing id field like we do when adding panels to a dashboard.

If a property is readOnly and also has a default, set the default as a static value on the object.

Code Generator

The code generator is a Go program in this repository. Currently only supported is Jsonnet for spec 7.0. Use it locally with:

go run . 7.0 jsonnet

This will produce the generated files in _gen/7.0/jsonnet/. Generated files are updated and committed to the _gen branch after every commit to master. See the Generated Code section for direct links.

Generated Code

The generated code lives in this repository's _gen branch.

Spec Documents

Libraries