Functions
A function is used by a Resource provider to combine measures into metrics. A Resource provider should define six JavaScript functions: meter, accumulate, aggregate, rate, summarize, and charge.
Considering these six functions, 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 is a "map" function, responsible for transforming raw measures into the units used for metering. In addition, the function often performs rounding or similar operations.
- input arguments:
-
m: submitted measure
-
The return value consists of the metered measure.
In Abacus example object store metering plan, a thousands of light API calls are metered, so the meter function will map the measure x to x / 1000:
(m) => new BigNumber(m.light_api_calls).div(1000).toNumber()The accumulate function is responsible for accumulating metered usage over time.
The input arguments are as follows:
-
a: current accumulated result -
qty: current measure -
start: start time of the resource usage -
end: end time of the resource usage -
from: the last time when the resource instance usage was accumulated. It remains 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. A typical use-case of the function is a sum of all metered usage for 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)Another example could be an "average" function with the help of a compound object:
(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 all of the input arguments are used in the examples above.
The aggregate function is responsible for aggregating usage in Cloud Foundry entities (spaces and organizations).
The input arguments are as follows:
-
a: current aggregated result. It is undefined if there is no usage -
prev: previous accumulated result. -
curr: current accumulated measure. It is undefined if the usage was rejected by accumulate -
aggTwCell: aggregation time-window cell -
accTwCell: accumulation time-window cell
The return value is the new aggregated result.
The function is usually used to add up usage from:
- different service instances under a service
- all the service instances under a space/app/org, and so on
In most of the cases, the function is used to sum up the measures as shown in the example object store metering plan:
(a, prev, curr, aggTwCell, accTwCell) => new BigNumber(a || 0).add(curr).sub(prev).toNumber()Rate is a simple "map" function, responsible for converting aggregated usage into cost. This can be done at various levels: service instance, plan, application, space, org, and so on.
The input arguments 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. In some cases the rate function could be more complex, for example: clip levels, pro-rating, and so forth.
The example object store rating plan uses simple multiplication to get the cost:
(price, qty) => new BigNumber(qty).mul(price || 0).toNumber()Summarize is a "reduce" function, responsible for summarizing the different types of usage.
It uses the following input arguments:
-
t: current summary -
qty: undefined if there is no usage -
from: the last time when the resource instance usage was summarized. It is 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 represents the summarized usage.
Charge is a "reduce" function, responsible for charging at various levels: service instance, plan, application, space, org, and so on.
Its input arguments are as follows:
-
t: current charges -
cost: cost (from the rate function) -
from: the last time when the resource instance usage was charged. It is 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 example object store rating plan uses the cost as charge and does nothing.
(t, cost, from, to) => cost ? cost : 0