prometheus-parser-rs

CircleCI docs.rs

prometheus-parser parses arbitrary Prometheus expressions into a syntax tree appropriate for syntax checking, linting, and general static analysis. It does not depend on a Prometheus server and works entirely offline.

This library is implemented in pure Rust (using [pest]) with no knowledge of the underlying Prometheus server implementation. It's been validated against the public Prometheus syntax documentation and various publicly available alert collections (e.g. [kubernetes-mixin]).

Note that this crate doesn't try to evaluate Prometheus expressions; consider using promtool's unit testing for this purpose.

Use cases

This library can be used to implement custom linting and static analysis tools, for example:

Limitations

Return value prediction

The library has a utility for predicting the return types of expressions based only on the syntax tree. This may be useful for rough static analysis.

Examples

examples/parse.rs

This can be used to dump the (slightly reduced) syntax tree for a given expression.

Try cargo run --example parse 'foo':

```bash $ cargo run --example parse 'countvalues by(service) ("confighash", alertmanagerconfighash{job="alertmanager-main",namespace="monitoring"}) / on(service) groupleft() labelreplace(max by(name, job, namespace, controller) (prometheusoperatorspec_replicas{controller="alertmanager",job="prometheus-operator",namespace="monitoring"}), "service", "alertmanager-$1", "name", "(.*)") != 1'

Operator { kind: NotEqual, lhs: Operator { kind: Divide, lhs: Function { name: "countvalues", args: [ # ... snip ... ], aggregation: Some( Aggregation { op: By, labels: [ "service", ], }, ), }, rhs: Function { name: "labelreplace", args: [ # ... snip ... ], aggregation: None, }, matching: Some( Matching { op: On, labels: [ "service", ], group: Some( MatchingGroup { op: Left, labels: [], }, ), }, ), }, rhs: 1.0, matching: None, } ```

Note that Expression has a Debug impl that somewhat reduces boilerplate output. It makes debug output more readable, but the displayed object structure won't exactly match the in-memory version. Specifically, if constructing your own AST objects, use the .wrap() utility functions present on most Expression subtypes to convert them to an Expression.

examples/reformat.rs

Parses the input expression and reformats it using the default Display impl.

bash $ cargo run --example reformat 'sum by(bar)(foo)' sum(foo) by (bar)

examples/return_value.rs

Displays the raw ReturnValue computed for a given expression.

```bash $ cargo run --example returnvalue 'foo(sum(foo))' ReturnValue { kind: InstantVector, labelops: [ LabelSetOpTuple { op: Clear, expression: Function { name: "sum", # ... snip ... }, span: Some( Span { start: 4, end: 12, }, ), }, ], }

```

examples/label_drop.rs

Shows where a label is dropped in an expression, if at all.

```bash $ cargo run --example label_drop 'foo(sum(foo))' namespace label 'namespace' is dropped:

foo(sum(foo)) --------

parent expression: sum(foo) ```

If an expression is invalid and has an unknown return type, a message will be printed:

```bash $ cargo run --example label_drop 'foo(sum(foo)) / bar[5m:]' namespace note: expression return type is unknown, result may be inaccurate reason: rhs return type (RangeVector) is not valid in an operator expression: foo(sum(foo)) / bar[5m:]

label 'namespace' is not dropped ```

examples/label_passthrough.rs

Shows the expected output labels for a given expression. Arguments after the expression are labels that exist on all input metrics.

Additional labels may be returned that were not present in the input list; these were inferred based on labels referenced in the expression.

bash $ cargo run --example label_passthrough 'sum by(bar)(foo)' baz { "bar", }

Contributing

Bug reports, feature requests, and pull requests are welcome! Be sure to read though the [code of conduct] for some pointers to get started.

Note that - as mentioned in the code of conduct - code contributions must indicate that you accept the Developer Certificate of Origin, essentially asserting you have the necessary rights to submit the code you're contributing under the project's license (MIT). If you agree, simply pass -s to git commit:

bash git commit -s [...]

... and Git will automatically append the required Signed-off-by: ... to the end of your commit message.