Stack language

Stack language is a way of specifying Prometheus queries to plot on a graph. It is adapted from Atlas Stack Language, which is itself based on RPN expressions supported by RRDtool. Here is an example of a stack language expression:

node_disk_read_bytes_total{node=app1},#0000FF,:color,42

This pushes on the stack a PromQL query, applies some styling on it (draw the line in blue), and pushes a constant value.

Goals and non-goals

Stack language is intended to be compact and URL-friendly. It is well adapted to the graph API which is designed around GET calls.

Stack language is an extension of PromQL, i.e., any valid PromQL expression is also a valid stack language expression. Moreover, is it by design organised around a syntax that does not look like PromQL, i.e., it does not try to add new primitives to PromQL but rather allows to combine or enrich PromQL expressions with another language.

Stack language sticks to adding presentation features to PromQL. It does not try to add new capabilies around time series manipulation. Said otherwise, data processing is done by Prometheus servers and not by Byblos.

Stack structure

Elements to push on the stack are separated by a comma. For example a defines a stack with a single element "a", while a,b defines a stack with two elements "a" and "b".

Commas nested inside brackets ([]), curly brackets ({}) or parens (()) are ignored. For example, metric{app=app1,status=200} defines a stack with a single element, ignoring the comma inside the selector.

Elements starting with a colon (:) are words, which define commands that manipulate the stack by evaluating, replacing, adding or removing elements. For example, a,:dup defines a stack that is equivalent to a,a once evaluated.

Parenthesis are used to define lists. Lists always contain litteral, i.e., commands are not executed. For example, (,a,:dup,) defines a stack with a single element, which is the list ["a", ":dup"].

Any double value that is left on the stack will get implicitly converted to a constant line. Any string value that is left on the stack will get implicitly converted to a query.

Variables

Variables can be used to store and retrieve any item in the stack. The following table contains a list of well-known variables:

Name	Description
tz	Timezone to use

Vocabulary

Words available in the stack language are presented in the other pages of this category. Please use the left navigation bar to get the definition of a word.