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. ratediff before

Now we apply ratediff() to the query find out how fast the counter grows from point to point.

ratediff after

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.

See Also

rate() Function