Language Specification

Composite metrics let you define a new higher-level metric by specifying an arbitrary set of mathematical transformations to perform on a selection of native metrics you’re sending us. You compose a new higher-level metric using the native metrics you send us as inputs. Alternatively you can think of it as a way to specify complex queries against your native metrics.

They are expressed as strings using the syntax described below and are parsed by Librato to execute a query that generates the desired result from the specified input metrics. A functional design approach is taken where a hierarchical nesting of functions uses the output of one (or a set) of function calls as the input into the next level.

Sets

Sets (or lists) of series are denoted in a similar fashion to JavaScript (and almost every other C-based language) using square brackets and commas:

[series1, series2, series3, ..., seriesN]

As these sets are not general purpose (e.g. as in JavaScript) but specifically intended to specify a list of series they have some additional capabilities. An element in a set specified by the user may actually be another set e.g. when the set members are each function calls that return a set of series. When a set is specified as a function input and some of its elements are sets, the parser will recursively expand/concatenate the nested lists of series in place until it has a set defined only as series. The sets returned by functions will never contain nested sets.

Functions

Every function takes as its input a set of series and (in some cases) a map of options and every function returns a set of series. Note that the cardinality of the set of series may be restricted in some cases. The only exception is the special function series() which imports raw metrics as a set of series (described below). A function is specified by the name and an adjacent set of parentheses (no intermittent whitespace permitted) that enclose its arguments:

function(arg1, arg2)

A function that takes a set of series as an argument can be specified using the square bracket set notation or the return of a single function. For example, the function foo(set[]) could be called in any of these forms:

foo(sum(series("a*", "b")))
foo([sum(series("a*", "b"))])
foo([series("a*", "b"), series("c*", "d")])

• Generator Functions
  • series(metric, source, options={})
• Transformation Functions
  • abs(set[])
  • derive(set[], options={})
  • divide(set[2])
  • fill(set[], options={})
  • filter(set[], options)
  • integrate(set[])
  • last_fill(set[])
  • max(set[])
  • mean(set[])
  • min(set[])
  • moving_average(set[], options={})
  • multiply(set[])
  • rate(set[], options = {})
  • scale(set[], options)
  • subtract(set[2])
  • sum(set[])
  • window(set[], options={})
  • zero_fill(set[])
• Enumerable
  • map(options, set[])
  • timeshift(shifts, set[])

Options

Some functions have optional or required option parameters. Options are key/value pairs that are specified in comma-separated form within curly-braces ({}). The key and value fields are separated by colons (:) and no whitespace. An empty options map looks like:

{ }

An options map with the two options period and function looks like:

{ period:"60", function:"sum" }

All option pairs must have a non-empty key and value. The option value must be quoted with double-quotes (“).