New Composite Metrics Language Functions: Scale and Rate — Librato Blog

# New Composite Metrics Language Functions: Scale and Rate

We are pleased to announce support for two new composite metric functions: scale() and rate().

When reporting metrics from multiple different systems and applications, it is common to report them in their raw form using the lowest common base unit and as aggregate sample counts. For example, the collectd monitoring daemon will report memory in bytes used, however we’re more commonly interested in megabytes or gigabytes. Or let’s say we want to take the number of HTTP requests we receive on our web tier and convert that to requests per second. To achieve these goals, Librato allows users to perform a “display transform” on the data on the display layer.

Today we’re unveiling two new composite functions that support the most common cases for display transforms at the API. Now you can use the same transform for both visualization and alerting.

### Scale Example

Scale is particularly useful when you want to convert raw bytes to a more human-readable format. In this example, we convert the metric collectd.memory.memory.used which is represented in bytes to a metric stream that is represented in megabytes (divides by 1024^2).

Composite definitions:

Result (the green line represents the raw data - the value in bytes; the blue line represents the scaled data - the value in megabytes):

scale(set[], options)

Given an arbitrary number of series, returns a set of equal length where each value has been multiplied by the transform factor in the options map. The one supported option is:

factor (required): number by which to multiply every value in the input series by. This value can be represented as a float value, e.g., “0.1”, “1.34”, “1024”, or as a simple fraction: “1/1024” (regex: `\d+/\d+`). The second format is provided as a convenience method so that common transforms (bytes->kilobytes) can be done without having to calculate the fractional float values.

### Rate Example

The following takes the count of successful http requests and performs the conversion against a default duration of 1, resulting in a calculation of requests per second.

Composite definitions:

Result (the green lines represent the total number of successful requests, whereas the blue lines represent the rate of requests per second):

rate(set[], options = {})

Given an arbitrary number of series, returns a set of equal length where each value has been converted to a rate over the defined duration. The duration of the period can be set with the following parameter:

duration: this converts every value to a rate, where the period of the rate is defined by the given duration. For every value “x”, the effective transform run is: (x / p * duration), where “p” is the automatic period of the data determined by the current rollup resolution, the saved metric period attribute, or the downsample period specified in a call to series(). For example, to get "rate per minute", you would set duration to "60" ( x / p * 60 ). Whereas, to get "rate per second", you would set duration to "1" ( x / p * 1). The duration defaults to “1” if not specified, implying all rates are converted to per-second.

How rate() detects the period:

• If a metric does not have a period set, then period is defaulted to resolution of the data.

• If the series() was given a ‘period’ parameter, it will be used in place of the metric period.

• When you switch to a higher viewing window, the data switches to a rollup resolution. Therefore, the period is calculated as the Max of (period, rollup resolution).

If you would like to learn more about composites take a look at our Composites Tutorial or the Composite Metrics Language Specification.

All of Librato's composite metrics functionality is available at no additional cost to our users. If you're not already using Librato, give it a try for free.