# 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¶

### 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[])
- top(set[], options={})
- window(set[], options={})
- zero_fill(set[])

### Enumerable¶

## 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 (“).**