[proposal] include keyword list in Prometheus distribution

[mtanda]

Grafana v4.5.0 will have query editor with auto complete.

The Prometheus keyword list is directly embed in Grafana code.
https://github.com/grafana/grafana/blob/v4.5.0-beta1/public/app/core/components/code_editor/mode-prometheus.js#L87-L323

It need to continuous maintenance in Grafana side, not updated automatically.
I think it is better to provide keyword list in Prometheus side, and update when new function is added.

cc: @torkelo @bergquist

[bergquist]

I had this exact conversation with @grobie after Promcon :)

Could the documentation for each function be included in the build?

Would also be great if we could get the helper text per serie from Prometheus. Getting an explanation for each serie within the editor would be helpful for many users. (idea by @grobie )

[grobie]

I fully agree that all these information should be owned and provided by the Prometheus server. The list of functions varies between Prometheus server versions, so Grafana should query an API endpoint to retrieve the set available at the queried server.

I'm currently working on versioned documentation, which will move the function documentation into the Prometheus server itself. I imagine to add a new API endpoint which returns the functions available including their documentation.

[brian-brazil]

This seems like a bit of an odd API to have, I'd expect something like Grafana to pick up the list at compile time rather than at runtime. This could also tie our hands in terms of language implementation as this would be an official API.

[grobie]

I'd expect something like Grafana to pick up the list at compile time rather than at runtime

Runtime means Grafana wouldn't need to be re-compiled when a new Prometheus version with new functions get released.

This could also tie our hands in terms of language implementation

Can you elaborate on this? PromQL functions are already part of our version guarantees.

[brian-brazil]

Can you elaborate on this? PromQL functions are already part of our version guarantees.

The issue requests "keywords". There's a chance the types of keywords we have may change over time, or implementation details will cause something to be added/removed that would be problematic.

[grobie]

The exact reason to have an API endpoint returning the available functions (the issue author used the term keywords interchangeably here, check the link) of a given Prometheus server is to exactly cater for the case of additions/changes.

[brian-brazil]

Keywords and functions are distinguished: https://github.com/grafana/grafana/blob/v4.5.0-beta1/public/app/core/components/code_editor/mode-prometheus.js#L10
That is presently entirely an implementation detail of the PromQL parser.

[davkal]

There are now a couple of promql editors out there, including the one I wrote.
For helping the wider adoption of Promql, I believe it would help a lot if inline documentation be made available, and if that was done centrally, i.e., data-driven by the backend.

From the user perspective the distinction between functions and keywords can seem arbitrary (e.g., what do you think topk() is?). Regardless, any kind of support, even if it we started with functions, would be a big help. On that note I'd be happy to do the implementation.

Random details:

• For prom's sanity we could keep the split between keywords and functions and simply offer two endpoints.
• Versioning the functions probably works best per item.
• We could add a snippet entry to each doc item, e.g., augmenting the DS that Grafana chose with snippet and version:

{
    name: 'abs()',
    value: 'abs',
    def: 'abs(v instant-vector)',
    docText: 'Returns the input vector with all sample values converted to their absolute value.',
    snippet: `abs($1)`,
    sinceVersion: 1.0
},

• A later PR could look into generating the relevant sections in the docs from code.

[tomwilkie]

+1 starting with functions seems like a step in the right direction.