Resource Counters

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.

Introduction to Counters

Monitoring Counters

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.

Additive versus Non-Additive

The platform classifies all resource counters as non-additive and additive. APS applications must use the same classification.

Non-Additive Counters

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

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.

Counters rated per Hour

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.

Resource Classes

Structures of type Counter and Limit (hereafter, counter structure or simply counter) inside an APS resource 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.

Limitations

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.

Scenario

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.

Start Your Demo Project

Clone the package you have created in the demo project of the Generic Services scenario to the new one by following these steps.

1. Create a new project basing on the input package and using one of the ways:

   • In APS IDE, import the package and then rename it, for example, assign it the counters name.
   • Copy all files of the input project to another folder, for example, to the counters/ folder.

2. 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.

3. To verify if there are no typo in the new project, try to build the new package using either Eclipse IDE, IDEA IDE, or the following command from 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.

← Internationalization (optional)

Provisioning Logic →