The APS types, except for those used to create APS application instances and a few other special types, implement the standard Resource APS type that defines the Counter, Limit, and Usage structures. An APS application can use those structures to measure and bill subscribers for storage, CPU power, and other countable resources used by the subscribed services.
This document explains how an APS application can make its resources countable by the platform. It also directs you through a demo project that logically follows the the Generic Services demo project.
Follow the scenario in this document if you want to practice in using APS counters to account resource consumption.
In this document:
To update periodically a counter usage, the platform creates the periodic task ‘Synchronize resource usage for APS application instance’ for each APS application instance. The provider can define the task period. Default period depends on the platform version.
The task requires the APS controller to call the retrieve method of the
respective APS resource.
The method must update the usage
property of the Counter
and Usage
structures if the resource
uses them.
Note
The platform recognizes counter updates in the respective subscription only if the application
updates its counters in the APS database when the APS controller calls the retrieve
operation of the application.
The retrieve
operation is declared as one of the APS Base CRUD Operations.
All other properties of the resource, that the method includes in its response, will be also updated on the APS controller side.
The platform classifies all resource counters as non-additive and additive. APS applications must use the same classification.
In the non-additive counter, the usage
can increase or decrease its value in each poll.
For example, a counter shows 200 GB of a storage usage in the first
poll, then this space increases up to 400 GB in the second poll, and then
decreases down to 300 GB in the third poll.
On completion of each billing period, usually a month, the platform BSS can use a counter to charge a customer
for the usage
averaged over the billing period.
Additive counters accumulate the usage
value, that is why the latter
cannot decrease. For example, if a VPS transfers data over a network channel,
the usage
of the network traffic increases when the VPS uses the channel
or stays at the same level when it does not transfer any data.
On completion of each billing period, usually a month, the platform BSS can use a counter to charge a customer
for the usage
accumulated during the billing period.
There are some counters that integrate a parameter of a resource usage over a time period.
The unit
property of such a counter is one of the following: item-h
, mhzh
, Kbit/sec-h
, or mb-h
.
This is similar to accounting the electrical energy in kWh.
Ideally, the usage
of such a counter is an integral
of a parameter over a time period started from the resource creation.
For example, for the mhzh
unit, it is the integral
of the CPU frequency usage measured in MHz over a time period started from the resource creation
and measured in hours. In reality, it depends on the application how close to the ideal formula
it computes the counter.
For example, if the clock rate of a CPU is 2.5 GHz and a VPS
uses 20% the CPU power during 3 hours, the usage
for that period is 2500*0.2*3 = 1500 MHz-hour.
Structures of type Counter
and Limit
(hereafter, counter structure or simply counter)
inside the abstract top-level Resource APS type can be used for billing the resource usage.
The Usage
structure bears only the information value.
To account resource usage in that way, a subscription must contain resource types of
the Application Counter resource classes. They present the Counter
(most often used) or Limit
structures of an APS resource inside the subscription.
We recommend you to use the mentioned structures of a singular APS resource
implementing the standard subscription service APS type.
This allows accounting resource usage for the whole subscription.
The platform has several Application Counter resource classes. When the provider
creates a resource type for one of the counter structures, they must select one of those resource classes
depending on the unit
property in the counter. To get a list of all resource classes,
start creating a resource type in the provider control panel and you will find them on the selection list:
The Application Counter (unit) resource class allows counting a number of some objects
used in a subscription. For example, it can be a number of allocated CPU cores. The unit
property of the counter must be either item
or unit
.
The Application Counter (KB) resource class is used to count
a storage space (for example, memory or disk) or a network traffic. The unit
is
either kb
, mb
, or gb
.
The Application Counter (kbps) resource class is used to count the data transfer speed
averaged over the polling period. The unit
of the counter must be kbps
.
The Application Counter (kbps-hours) resource class is used
for additive
counters that estimate the usage of a network bandwidth over a period of time.
The unit
of the counter must be Kbit/sec-h
. For example, if a subscription service
rents the 200 kbps bandwidth during 10 hours, the bandwidth usage
for that period is 200*10 = 2000 kbps-hour.
The Application Counter (MHz) resource class is used to count the CPU power
used by a resource (for example, by a VPS)
averaged over the polling period. The unit
of the counter must be mhz
.
The Application Counter (unit-hours) resource class is used
for additive
counters that estimate the integral usage of a number of objects over a period of time.
The unit
of the counter must be item-h
. For example, if a VPS
uses 4 CPU cores during 10 hours, the usage
for that period is 4*10 = 40 unit-hour.
The Application Counter (MB-hours) resource class is used
for additive
counters that estimate the usage of a space over a period of time. The unit
of the counter must be mb-h
.
For example, if a subscription service
uses 4000 MB of memory during 10 hours, the usage
for that period is 4000*10 = 40000 MB-hour.
The Application Counter (MHz-hours) resource class is used
for special additive
counters that estimate the usage of CPU power over a period of time. The unit
of the counter must be mhzh
.
For example, if the clock rate of a CPU is 2.5 GHz and a VPS
uses 20% the CPU power during 10 hours, the usage
for that period is 2500*0.2*10 = 5000 MHz-hour.
Suppose an application has its own base APS type ‘A’ that implements the standard APS type Resource and there is an APS type ‘C’ implementing that base APS type ‘A’. The service template will include a resource type presenting the derived APS type ‘C’ and resource types presenting counters.
In that case, to avoid confusion during configuration of the resource types for the counters, do not declare the variables presenting the counters in the base APS type ‘A’. Instead, declare those variables directly in the APS type ‘C’ as explained in the Declare Resource Counters step of the demo project.
The application to be developed in this project will allow the provider and subscribers to get statistics on actual resource consumption using additive and non-additive resource counters. A subscription will allow the subscriber to have many virtual servers. The counters in the subscription service will compute the total usage of various resources in the subscription: CPU, memory, and disk space:
CPU power of a virtual private server (VPS) is defined by the number of CPU cores allocated for it.
Let us assume the application vendor is interested in counting
the CPU usage per time, that is on the additive basis, using the item-hour
unit.
Memory space (RAM) will be counted similar to the above resource, but the unit of measure will be MB-hour
.
For disk space (Disk) we will use the non-additive method by measuring its usage in GB
.
Clone the package you have created in the demo project of the Generic Services scenario to the new one by following these steps.
Create a new project based on the input package by extracting the package to a new folder, for example,
to the counters/
folder.
Replace every occurrence of the application ID and type ID prefix with
“http://aps-standard.org/samples/counters/” in APP-META.xml
, PHP, HTML, and JavaScript files.
This will replace the old application and types with the new ones.
To verify if there are no typo in the new project, try to build the new package using the command line tools:
$ aps build counters
If no errors detected and you have successfully built a new APS package, then proceed to the next step.