Functions

In order to combine the measures into metrics, a resource provider can define six JavaScript functions: meter, accumulate, aggregate, rate, summarize, and charge.

The Abacus processing pipeline is a simple composition that can be expressed as follows:

charge(…, summarize(…, rate(aggregate(..., accumulate(..., meter(usage)))))))

The functions work with Math global object and BigNumber.js to allow higher precision of the result.

The six functions are as follows:

• meter
• accumulate
• aggregate
• rate
• summarize
• charge

meter

Meter is a "map" function, responsible for transforming a raw measure into the unit used for metering. In addition, the function often performs rounding or similar operations.

• input arguments:
  • m: submitted measure
• return value: metered measure

In this example, we want to meter thousands of API calls so the meter function will map the measure x to x / 1000:

(m) => new BigNumber(m.storage).div(1073741824).toNumber()).toString(

accumulate

Accumulate is a "reduce" function, responsible for accumulating metered usage over time.

The input arguments are as follows:

• a: accumulated result so far
• qty: current measure
• start: start time of the resource usage
• end: end time of the resource usage
• from: the last time at which the resource instance usage was accumulated. undefined if there is no previous accumulated usage for the resource instance by a specific consumer
• to: the time to which the resource instance usage must be accumulated
• twCell: time-window cell

The return value consists of the new accumulated result and a typical use case is the sum of all metered usage for given a resource instance over time.

The function is often implemented as a maximum value over a given period of time. For example, the object store finds the maximum memory used by the storage, as shown below:

((a, qty, start, end, from, to, twCell) => end < from || end >= to ? null : Math.max(a, qty)).toString()

An "average" function can be realized with the help of a compound object as follows:

(a, c) => a ? { sum: a.sum + c, count: a.count + 1,avg: (a.sum + c) / (a.count + 1) } : { sum: c, count: 1, avg: c } }

Note that not use all input arguments are used in the examples above.

aggregate

Aggregate is a "reduce" function responsible for aggregating usage in Cloud Foundry entities (spaces and organizations).

The input arguments are as follows:

• a: aggregateed result so far. undefined if no usage
• prev: previous aggregateed result
• curr: current measure. undefined if usage was rejected by accumulate
• aggTwCell: aggregation time-window cell
• accuTwCell: accumulation time-window cell

The return value is the new aggregated result.

Usually, the function is used to add up usage from:

• different service instances under a service
• all the service instances under a space/app/org, etc.

Most commonly, the function is used to sum up the measures, as shown in our object store example below:

((a, prev, curr, aggTwCell, accTwCell) => new BigNumber(a || 0).add(curr).sub(prev).toNumber()).toString()

rate

Rate is a simple "map" function, responsible for converting an aggregated usage into cost. This can be done at various levels: service instance, plan, app, space, org, etc.

The input argument are as follows:

• price: price of the usage
• qty: aggregated usage quantity

The return value represents the cost.

A typical rate function will multiply the metered usage by a given price in order to get the cost, but you can also use more sophisticated rate functions for clip levels, pro-rating, etc.

The object store rating plan uses simple multiplication to get the cost:

((price, qty) => new BigNumber(qty).mul(price || 0).toNumber()).toString()

summarize

Summarize is a "reduce" function, responsible for summarizing the different types of usage.

It uses the following input arguments:

• t: summary so far
• qty: undefined if no usage
• from: the last time at which the resource instance usage was summarized. undefined if there is no previous summary for the resource instance by a specific consumer
• to: the time to which the resource instance usage must be summarized

The return value shows the summarized usage.

charge

Charge is a "reduce" function, responsible for charging at various levels: service instance, plan, app, space, org, etc.

Its input arguments are as follows:

• t: charges so far
• cost: cost (from the rate function)
• from: the last time at which the resource instance usage was charged. undefined if there is no previous charge for the resource instance by a specific consumer
• to: the time to which the resource instance usage must be charged The return value is the charge.

The rating planrating plan uses the cost as charge (does nothing):

((t, cost, from, to) => cost ? cost : 0).toString()