Document the use of Templating

[erkolson]

What you expected to happen?

I attempted to use add templating to a dashboard, it is not documented how to use it so I provided these parameters: https://github.com/aknuds1/grafanalib/blob/master/grafanalib/core.py#L431-L439

        :param default: the default value for the variable
        :param dataSource: where to fetch the values for the variable from
        :param label: the variable's human label
        :param name: the variable's name
        :param query: the query users to fetch the valid values of the variable
        :param allValue: specify a custom all value with regex,
            globs or lucene syntax.
        :param includeAll: Add a special All option whose value includes
            all options.

What happened?

Js error in grafana when trying to import the resulting json dashboard. After some effort I determined that the js error is caued by the absence of some of these values for each template: https://github.com/aknuds1/grafanalib/blob/master/grafanalib/core.py#L456-L470

    def to_json_data(self):
        return {**_as_dict(self), **{
            'current': {
                'text': self.default,
                'value': self.default,
                'tags': [],
            },
            'hide': 0,
            'multi': False,
            'options': [],
            'refresh': 1,
            'regex': '',
            'sort': 1,
            'tagValuesQuery': None,
            'tagsQuery': None,
            'type': 'query',
        }}

I'm not very familiar with python but that bit of code looks like it should be used as defaults? In any case, when I include those keys/values for each templated variable in my dashboard.py, the resulting json generated does work!

How to reproduce it?

Create any dashboard that uses the templating, i.e.:

  templating=Templating(list=[
    { # namespace
      "default": "",
      "datasource": "prometheus",
      "label": "Namespace",
      "name": "namespace",
      "query": "label_values(kube_pod_info, namespace)",
      "allValue": ".+",
      "includeAll": True,
    },
  ]),

Is this a bug with how templating gets rendered? If not, can you add the proper incantation to use templating in the example dashboard.py?

[jml]

Thanks! This looks like a bug. I hope to try to fix it soon, but am stretched pretty thin.

[taion809]

@jml do you have any thoughts as to where this bug might be? I looked through the code a bit and it's not really clear why this would work as expected.

also as a workaround you can explicitly pass the template object.

dashboard = G.Dashboard(
    title="Summary",
    templating=G.Templating(list=[
        G.Template(
            default="east-platform",
            dataSource="prometheus",
            name="data_source",
            label="Data source",
            query="prometheus"
        )
    ])
)

[jml]

I think it's just missing values in one of the objects. Isolating it is made more complicated by the fact that the bug is only revealed when the generated JSON is loaded by Grafana itself.

I won't have time to get into this for a little while.

[matthewmrichter]

Bump - may take a look at fixing this myself.

[matthewmrichter]

On the Grafana side, the defaults appear to be here: https://github.com/grafana/grafana/blob/85dad73e9de458ed8610ce7acdb326ff72808970/public/app/features/templating/query_variable.ts#L47-L68

defaults: QueryVariableModel = {
    type: 'query',
    name: '',
    label: null,
    hide: VariableHide.dontHide,
    skipUrlSync: false,
    datasource: null,
    query: '',
    regex: '',
    sort: VariableSort.disabled,
    refresh: VariableRefresh.never,
    multi: false,
    includeAll: false,
    allValue: null,
    options: [],
    current: {} as VariableOption,
    tags: [],
    useTags: false,
    tagsQuery: '',
    tagValuesQuery: '',
    definition: '',
  };

[chrisfleming]

I'm still checking this out - but I think I've found the problem, in my experimentation, it looks like 'selected' has to be set to either True or False to get things working https://github.com/chrisfleming/grafanalib/commit/0589cb5e67084e9c63669514d3efa267b44cbcc4

I've a few more checks but should have a pull request next week.

[JamesGibo]

Thanks Chis, look forward to the PR.

[JamesGibo]

Could templating still be improved with some better docs? Or do we think this issue can be closed?