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.
|expression||Expression describing the time series to return differences for.|
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
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:
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.
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.
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.
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.
- 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.