# Composite Metrics Tutorial¶

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 or *time-series* you’re sending to Librato.
Alternatively you can think of composite metrics as a very powerful way to specify
arbitrarily complex queries against your native metrics.

Composite metrics can be saved in charts, and correlated with native metrics in the same chart. You can assign properties like y-axis titles and tool-tip aliases to them just like you do to native metrics.

If you need help building composites, don’t hesitate to contact support or post a question on StackOverflow using the #librato tag.

There are two ways to create composites: in a chart and as a persisted composite.

## Composites in a Chart¶

To create a composite in a chart, create a new chart or edit an existing one, then click on the Composite Metric Editor button to the right of the metric search field. This will open the composite editor.

## Persisted Composites¶

Composites can be saved for using on multiple charts or to use as an alert condition. Head on over to your metrics tab and click on the Create Composite Metric button in the upper right corner.

From there you can enter in the composite definition and save it so it can be used globally like you would use any other metric.

## Composing Metric Queries¶

The composite metrics editor provides a text field into which you can type a query that will create a composite metric in the graph. Queries are composed of time-series wrapped in functions in the general form:

```
function(series(metric,tags)))
```

Note

You cannot nest composite metrics.

Lets take a quick tour of the DSL used to create and work with composite metrics.

## Sets and the Series() Function¶

Composite metrics are created from sets and functions. A time series is
a stream of time-aligned measurements of the sort that is identified by
a combination of metric name and tag(s) in our metrics platform. A
set is a list of time series. For example, if you have a metric called
“librato.load.load.shortterm”, and one tag called “host” with three values
representing three hosts (server1, server2 and server3) which emit that metric,
then the combination of the metric name and tag with a wildcard `{"host":"*"}`

specifies a set of three time series: librato.load.load.shortterm across
each of the three different servers.

The series() function is used to retrieve sets of measurements from your existing metrics data. It takes three arguments; the first: metric name, and second: tag set (includes a name/value combination), are required, and the third is optional (we’ll get to that in a moment). Here are some examples using the series() function:

```
series("librato.load.load.shortterm", {})
```

… will retrieve all measurements for the librato.load.load.shortterm metric. Empty curly brackets are interpreted as “all tags”.

```
series("librato.load.load.shortterm", {"host":"*"})
```

… will retrieve the set of measurements from each value of the host tag (server1, server2 and server3 in our example).

```
series("librato.load.load.shortterm", {"host":"server1"})
```

… will retrieve only the set of measurements from server1.

You can use wildcards in the metric name too. So a series() invocation like this…

```
series("librato.load.*", {"host":"*"})
```

… will retrieve a set containing the 5, 10, and 15 minute cpu load metrics (shortterm, midterm, and longterm) from all hosts.

### Varying the Summary Function¶

By default the summary statistic function used in each time-series is
the *average*, you can change this by setting the *function* option to
the series call to one of min, max, count, sum:

```
series("cpu.load.*", {"host":"server*"}, {function:"sum"})
```

### Varying the Resolution¶

You can also alter the granularity of the summarized data. By default a
query for the last 14 days will return time-series with hourly
datapoints i.e. *period=”3600”*. With the *period* option you can
specify an arbitrary resolution in seconds to which the datapoints
should be rolled up. For example, to specify daily resolution using
*sum* as the summary function:

```
series("cpu.load.*", {"host":"server*"}, {function:"sum",period:"86400"})
```

### Shorthand Notation¶

As every composite metric definition contains at least one invocation of
*series()* and more sophisticated defintions may contain several, our
grammar supports *s()* as an equivalent shorthand notation e.g.:

```
s("cpu.load.*", {"host":"server*"}, {function:"sum",period:"86400"})
```

### Sets of sets¶

Finally we can create sets of sets by square-bracketing series() calls. We can use this to specify multiple series as a single argument to functions like divide(), as we’ll see shortly, or to make more specific typeglobs, for example to specify the shortterm and longterm load averages, but not the midterm average we could use:

```
[s("librato.load.load.shortterm",{"host":"*"}),
s("librato.load.load.longterm",{"host":"*"})]
```

## Dynamic Tags¶

When you add a metric to a chart, our user interface supports
the concept of dynamic tags, which is a fancy way of saying that
you’ll specify the value of the tag(s) later on when you actually want to view the
data. You can use dynamic tags in
your composite metric definitions by using `%`

in lieu of the tag(s)
argument to *series()*. We could make our set of load averages dynamic like so:

```
[s("librato.load.load.shortterm","%"),
s("librato.load.load.longterm","%")]
```

## Aggregation and Transformation Functions¶

Composite metrics are created by applying transformation and aggregation
functions to the native time-series data returned from *series()*. Each
function takes both a set as input and returns a set as output, so
functions can nest each other ad infinitum. Below are examples of commonly used functions.

### sum()¶

The *sum()* function aggregates the input set down to a single series by
adding together the measurements at each time interval. You get a single
time series consisting of all the input series added together.

If, for example, you had several metrics that tracked the occurrences of HTTP response codes in your logs, you could get a total count of HTTP 4xx-series errors across all hosts using the sum function like so:

```
sum(s("prod.log.http.4*",{"host":"*"}))
```

You could use a set of sets to capture 4xx and 5xx errors like so:

```
sum([
s("prod.log.http.4*",{"host":"*"}),
s("prod.log.http.5*",{"host":"*"})])
```

### subtract()¶

The *subtract()* function takes a set of exactly two time series and
returns the result of subtracting the second from the first.

Continuing from the last example, if you tracked the occurrences of HTTP
response codes in your logs, you could get a count of all non-200
responses by combining *sum()* and *subtract()* in a set of sets like
so:

```
subtract([
sum(s("prod.log.http.*",{"host":"*"})),
sum(s("prod.log.http.2*",{"host":"*"}))])
```

### max()¶

The max() function aggregates the input set down to a single series by discarding all but the largest measurement at each time interval. You get a single time series consisting of the largest single measurement from each of the input series.

If you wanted to monitor load average site-wide with a single line, you
could use the *max()* function to display the site-wide maximum load
average.

```
max(s("librato.load.load.*",{"host":"*"}))
```

### min()¶

The *min()* function aggregates the input set down to a single series by
discarding all but the smallest measurement in each time interval. You
get a single time series consisting of the smallest single measurement
from each of the input series.

You could add a lower bound to the site-wide load average graph with a
call to *min()* like so…

```
min(s("librato.load.load.*",{"host":"*"}))
```

### mean()¶

The *mean()* function aggregates the input set down to a single series
by computing the mean of all measurement in each time interval. You get
a single time series consisting of the mean of the input series.

Adding the mean to our site-wide load average graph with *mean()* like
so…

```
mean(s("librato.load.load.*",{"host":"*"}))
```

… yields a graph that represents the average CPU load across our entire infrastructure.

### derive()¶

The *derive()* function is useful when you want to view the rate of
change of a given metric - how much it increases or decreases from one
measurement to the next. It transforms the input set by computing the
derivative of each series in the set. Unlike the functions we’ve
discussed thus far, *derive()* doesn’t aggregate, or combine the input
set, you get as many series out as you put in. In order to avoid certain
edge cases involving late-arriving data, we recommend that you push
calls to *derive()* to the lowest, or innermost, possible level, e.g:

```
sum(derive(series()))
```

is preferable to:

```
derive(sum(series()))
```

You can track the rate of customer signups by using *derive()* to graph
the rate of change in a total user count metric.

```
derive(s("prod.myapp.users.count", {"host":"*"}))
```

### divide()¶

It’s often useful to calculate the ratio of two metrics. The *divide()*
function takes a set of exactly 2 time series and returns the result of
dividing the first by the second (The first set is used as the dividend
and the second, the divisor). Continuing the last example, if we were
tracking sign-ups and churn on a per-server basis, you could track the
ratio of new customers to cancellations by first aggregating all of the
per-server stats with *sum()*, and then dividing the result like so:

```
divide([
sum(s("prod.myapp.signups", {"host":"*"})),
sum(s("prod.myapp.cancels", {"host":"*"}))
])
```

### group_by()¶

Sometimes you may want to aggregate the results of a particular composite by a set of one or more shared tag names, which you can do with the `group_by`

function. It takes as its first argument a comma-separated list of one or more tag names to group the remaining composite function by, specified by the second parameter. It is as if the enclosed composite function is executed once per unique set of tag values for the grouped tag names. For example, if you wanted insight on user signups based on location, you could group them into similar regions by doing the following:

```
group_by("region", sum(series("prod.myapp.signups", {"region" : "*east"})))
```

which is equivalent to the following composite function:

```
[sum(series("prod.myapp.signups", {"region" : "north-east"})),
sum(series("prod.myapp.signups", {"region" : "south-east"}))]
```

## A real-world use-case¶

The Librato Agent reports CPU usage broken and per-type e.g.:

```
librato.cpu.percent.user
librato.cpu.percent.system
```

Assume we want to graph the total *system* CPU usage on a server
*server-instance-1*. We’d start constructing our composite metric by
retrieving the native metrics that detail system CPU usage for each
core:

```
series("librato.cpu.percent.system", {"host":"server-instance-1"})
```

Now we can see how the system CPU usage changes over time, but it’s
still in abstract units of time. It’s more useful/intuitive to examine
system CPU usage in relation to the total capacity available on the
server. We can effect this by taking a ratio of the system CPU usage to
the total CPU usage (which include *idle*). Note that we used the
*[series1, series2]* set notation to specify the inputs to *divide()*:

```
divide(
[
series("librato.cpu.percent.system", {"host":"server-instance-1"}),
sum(series("librato.cpu.percent.*", {"host":"server-instance-1"}))
])
```

Finally we can make our composite applicable to any server by switching
to a dynamic tag and slightly briefer
with the *s()* shorthand for *series()*:

```
divide(
[
s("librato.cpu.percent.system", "%"),
sum(s("librato.cpu.percent.*", "%"))
])
```

### Language Specification¶

Learn more by taking a quick tour of the DSL used to create and work with composite metrics.

If you have questions about composites, contact support or post a question on StackOverflow using the #librato tag.