Reference to the ratediff() function

## Summary

``````ratediff(<expression>)
``````

Returns the differences between adjacent values in each time series described by the expression. The results include only positive changes in value. Use `rate()` if you want to see per-second rates of change.

## Parameters

ParameterDescription
expression Expression describing the time series to return differences for.

## Description

The `ratediff()` standard time function returns the differences between adjacent increasing data values in the time series described by the expression. For example, consider a metric that counts the cumulative number of logins for an application over time. You can use the `ratediff()` function to see how many logins were added from one reported data point to the next.

`ratediff()` returns a separate series of results for each time series described by the expression.

`ratediff()` returns only positive changes in value. As a result, it’s primarily useful for counter metrics, which are metrics that report cumulative totals (increasing values) over time.

`ratediff()` is similar to Graphite’s `nonNegativeDerivative()` function.

### Change in Value

`ratediff()` returns the change in value from one data point to the next, rather than computing a rate of change over time. For example, let’s say that a metric has a reporting interval of 30 seconds, and reports these successive data values:

 Value Time 105,500 05:45:00pm 105,750 05:45:30pm

`ratediff()` subtracts the second data value from the first one (`105,750 - 105,500`) and returns the resulting value (`250`) at 05:45:30pm. The difference between these data values would be exactly the same if the metric had reported them two minutes apart.

Because `ratediff()` ignores the time interval between reported data values, it is useful for time series that have gaps or irregular reporting intervals. Use `rate()` if you want to see per-second rates of change for time series with relatively regular reporting intervals and few gaps.

Note: `ratediff()` treats the first data value reported by a time series as if it were preceded by 0. Consequently, the first value returned by `ratediff()` is the same as the first data value in the input series.

### Response to Counter Resets

A counter metric normally produces an monotonically increasing series of data values, which produce positive changes in value. However, a metric might reset its counter on occasion – for example, if the metric’s source restarts.

A metric indicates a counter reset by reporting a lower data value immediately after a higher data value. `ratediff()` responds to a counter reset by returning the lower data value. Specifically, `ratediff()` treats the lower data value as if it were preceded by 0, and returns the difference between that value and the inferred 0.

`ratediff()` never returns a negative change in value.

## Examples

Here’s a query that shows a sample metric that increments a counter. The reporting interval is 2 seconds, which means the counter increments every 2 seconds. We see the count climb from 8:50:36 to 8:50:51, when it resets. The counter restarts at 8:50:55. Now we apply `ratediff()` to the query find out how fast the counter grows from point to point. Notice:

• The first value returned by `ratediff()` is 2, which is the counter’s first value minus an inferred value of 0.
• `ratediff()` returns no value when the counter skips a point at roughly 8:50:53.
• When the counter restarts at 8:50:55, `ratediff()` returns 2, which is the counter’s first value after the restart, minus an inferred value of 0.
• The two points reported after the counter restarts have the same value (2), causing `ratediff()` to dip down to 0 at 8:50:57.

`rate()` Function