Previous topic

Offering Management

Next topic

Offer-Counter-User Management

DOCUMENTATION
Last updated 12-Sep-2016

Resource Consumption Monitoring

Input data: Sample VPS Cloud Basic package

Purpose

The project allows the provider and subscribers to get statistics on actual resource consumption. In the customer CP, we will add the ability to monitor resource consumption. Providers will be able to upsell resource usage and charge customers for actual resource consumption.

Following this project, you will create an APS package similar to the sample package in the APS catalog.

Resource Model

We do not need to add any new types here, and the project still contains three APS types. We are going to count CPU, RAM, and disk usage. Therefore, the respective properties and functions must be added to the VPS provisioning logic.

../../../_images/demo-counter-relations.png

Transition to new Application

We will convert the old application to the new one by following these steps:

  • Copy the contents of the basic folder to the new counter-mgmt folder.

  • Replace every occurrence of application ID and type ID prefix with “http://aps-standard.org/samples/counters/” in APP-META.xml, all PHP scripts, and all UI scripts.

  • To verify if there are no substantial typos in the new project, try to build the new package:

    aps build counter-mgmt
    

    If no errors detected and you have successfully built a new APS package, then you can proceed with the following steps.

Meta Description

In the project workspace, e.g. /aps/workspace/counter-mgmt, edit the APP-META.xml file by using a text editor or the APS IDE as follows:

  • In the CCP navigation tree, add the counters item labeled as Resource Usage that must present the resource usage for customers. Make it a child of the <navigation> element.
  • Inside this item, add the counters view labeled as Resource Usage.

After respective modifications, the new declaration inside the CCP <navigation> element looks as follows:

<item id="counters" label="Resource Usage">
   <view id="counters" label="Resource Usage"></view>
</item>

Provisioning Logic

Service Overview

In this project, we neither add new services nor modify any relations. Thus, the list of services and relations remains the same as we used in the Resource Model of the previous project.

Type Name Type ID Relation Relation parameters
Cloud http://aps-standard.org/samples/counters/cloud/1.0 contexts Collection-Optional
Context http://aps-standard.org/samples/counters/context/1.0
cloud
vpses
Singular-Required
Collection-Optional
VPS http://aps-standard.org/samples/counters/vps/1.0 context Singular-Required

To account resource usage in the subscription, we need to add APS counters to the provisioning logic of the management context. The latter is linked with all VPSes consuming resources that allows it to poll the VPSes for the actual resource usage.

Management Context Logic

In the contexts.php file, we use the APS counter structure defined in the APS core Resource type. In accordance with it, the resource counters are declared as follows:

/**
 * @type("http://aps-standard.org/types/core/resource/1.0#Counter")
 * @description("Total Disk Space Usage")
 * @unit("gb")
 */
public $diskusagetotal;

/**
 * @type("http://aps-standard.org/types/core/resource/1.0#Counter")
 * @description("Total CPU usage")
 * @unit("unit")
 */
public $cpuusagetotal;

/**
 * @type("http://aps-standard.org/types/core/resource/1.0#Counter")
 * @description("Total Memory usage")
 * @unit("mb")
 */
public $memoryusagetotal;

For each counter, we declare its APS type, description, measure unit, and the variable name. The generated schemas/contexts.schema.gen file in the built APS package must contain the following sections:

{...
"diskusagetotal": {
   "type": "http://aps-standard.org/types/core/resource/1.0#Counter",
   "description": "Total Disk Space Usage",
   "unit": "gb"
 },
 "cpuusagetotal": {
   "type": "http://aps-standard.org/types/core/resource/1.0#Counter",
   "description": "Total CPU usage",
   "unit": "unit"
 },
 "memoryusagetotal": {
   "type": "http://aps-standard.org/types/core/resource/1.0#Counter",
   "description": "Total Memory usage",
   "unit": "mb"
 },...
}

Once the resource (management context) and its counters are provisioned in a subscription, the hosting platform will periodically call the retrieve() function of the respective service. Thus, we need to define this function in contexts.php.

  1. Build the typical function structure:

    public function retrieve() {
       ## Connect to the APS controller
    
       ## Reset the local variables
    
       ## Collect resource usage from all VPSes
       foreach ($this->vpses as $vps) {
    
       }
    
       ## Update the APS resource counters
    
    }
    
  2. Inside the function, connect to the APS controller and initialize local variables:

    ## Connect to the APS controller
    $apsc = \APS\Request::getController();
    
    ## Reset the local variables
    $disk = 0;
    $ram = 0;
    $cpu = 0;
    
  3. Gather resource usage by calling the proper function for each VPS:

    foreach ($this->vpses as $vps) {
       $usage = $apsc->getIo()->sendRequest(\APS\Proto::GET,
             $apsc->getIo()->resourcePath($vps->aps->id, 'updateResourceUsage'));
       $usage = json_decode($usage);
       $disk = $disk + $usage->diskActualUsage;
       $ram = $ram + $usage->ramActualUsage;
       $cpu = $cpu + $usage->cpuActualUsage;
    }
    

    In this code, we get the list of VPSes through the vpses relation. We suppose to use the updateResourceUsage() custom method that must be defined in the vpses services.

  4. Update the APS counters in the context resource:

    $this->diskusagetotal->usage = $disk;
    $this->memoryusagetotal->usage = $ram;
    $this->cpuusagetotal->usage = $cpu;
    

Server Monitoring Logic

In the vpses.php script, we do not use APS counters. Instead, we update custom resource usage properties on a custom request and return the requested parameters.

Define the local properties for monitoring actual resource usage in a VPS:

/**
 * @type("integer")
 * @title("CPU actual usage")
 * @description("CPU cores actual usage")
 */
public $cpuActualUsage;

/**
 * @type("integer")
 * @title("RAM actual usage")
 * @description("RAM space actual usage")
 */
public $ramActualUsage;

/**
 * @type("integer")
 * @title("Disk actual usage")
 * @description("Disk space actual usage")
 */
public $diskActualUsage;

These additional VPS properties will allow collecting resource usage per VPS directly by the standard REST GET request when needed.

Define the custom updateResourceUsage() function that updates the VPS properties declared above and return their values.

  1. Define the function as an APS operation using proper decorators in the PHP /** ... */ comments:

    /**
     * Set random values to resource usage and return them back
     * @verb(GET)
     * @path("/updateResourceUsage")
     */
    public function updateResourceUsage () {
       $usage = array();
    
       ## Calculate the resource usage properties
    
       return $usage;  // Return resource usage
    }
    
  2. Inside the function, calculate the properties that present resource usage for a VPS:

    $this->cpuActualUsage = rand(1,32);
    $usage['cpuActualUsage'] = $this->cpuActualUsage;
    
    $this->ramActualUsage = rand(100,5000);
    $usage['ramActualUsage'] = $this->ramActualUsage;
    
    $this->diskActualUsage = rand(1,100);
    $usage['diskActualUsage'] = $this->diskActualUsage;
    
    ## Save resource usage in the APS controller
    $apsc = \APS\Request::getController();
    $apsc->updateResource($this);
    

    In this code, we update resource usage with random values, thus imitating a real case.

Presentation Logic

Presentation Overview

In the Service Automation customer CP, APS counters added as Operations Automation resources to a subscription, are available in a standard view. A subscriber can open the list of resources for a selected subscription, by clicking Resource Usage on the Home tab. It means, we do not need to develop any custom UI view for watching resource usage in a subscription.

Suppose customers need to track resources used by each VPS. Therefore, in this project, we use a custom UI for watching per VPS resource usage. In APP-META.xml, we declared the navigation tree with the new counters view that must be implemented in the new counters.html file. We do not need to edit any other files in the ui folder.

Counters View

The counters.html file displays a table with a list of VPSes. The table includes three columns with the resource usage values. The file is pretty small, and thus its whole contents is presented here:

<!DOCTYPE html>
<html>
<head>
<script src="/aps/2/ui/runtime/client/aps/aps.js"></script>
<script>
require([
   "aps/ResourceStore",
   "aps/load",
   "aps/ready!"
], function (Store, load) {
   var store = new Store({
	    apsType: "http://aps-standard.org/samples/counters/vps/1.0",
	    target: "/aps/2/resources/"
   });
   
   load(["aps/PageContainer", { id: "page" }, [
    ["aps/Grid", {
      id: "counters_grid",
      store: store,
      apsResourceViewId: "server.edit",
      columns: [
         { field: "name", name: "Name", filter: { title: "Name" },
           type: "resourceName" },
         { field: "ramActualUsage", name: "RAM (MB)", filter: { title: "RAM" } },
         { field: "diskActualUsage", name: "Disk Space (GB)",
           filter: { title: "Disk Usage" } },
         { field: "cpuActualUsage", name: "CPU (cores)" },
         { field: "platform.OS.name", name: "OS" },
         { field: "state", name: "State" }
       ]
    }]
   ]]);
}	/* end of main call-back function  */
);	/* end of require */
</script>
</head>
<body>
</body>
</html>

Deployment

Building Package

Build the package from the project folder counter-mgmt using APS IDE or the following command:

aps build counter-mgmt

Package Import

Import the package as described in the Package Import section.

Setting Application Endpoint

We suppose you have practice in creating an endpoint as described in the Starter demo project. Now, we need to create a new endpoint or update the existing one as follows:

  1. Copy the updated PHP files from the project scripts folder to the endpoint root folder.
  2. Make sure the apache:apache owners are assigned to the updated files.

Installing Application Instance

The process is generally described at Application Instance Installation. Follow the steps in the Installing Application Instance section of the Starter project to install the application instance.

Creating Resources

In accordance with the resource map and the resource relation diagram, we need to create the following Operations Automation resource types (RT) basing on respective resource classes (RC) for representing APS resources:

APS Service Operations Automation RC Operations Automation RT Description
VPS cloud globals Application Service Reference Counters - App REF Application instance
VPS Management Application Service Counters - VPS Management Customer management environment (context)
Virtual Private Server Application Service Counters - Virtual Private Server Customer’s virtual server
CPU Usage Counter Application Counter (unit) Counters - CPU Usage total Counter of CPU cores actually used
RAM Usage Counter Application Counter (kb) Counters - RAM Usage total Counter of RAM space actually used
Disk Usage Counter Application Counter (kb) Counters - Disk Usage total Counter of disk space actually used

Follow the steps described in the Creating Resources section of the Starter project to create the Operations Automation resource types.

Note

Keep in mind that the VPS Management resource type must be marked as Automatically provision service. Make sure the check-box is clean for the other resources.

Now, we have all Operations Automation resource types that can be used for creating a service template in Operations Automation.

Creating Service Template

Generally, the process is described in the Creating Operations Automation Service Template section. Follow the steps in the Creating Service Template section of the Starter project to create a new service template called Cloud VPS Services - Counter Project and add all the application resources to it. Finally, it must look as follows:

../../../_images/pa-demo-counter-st.png

Provisioning

At the provisioning stage, we will verify if a subscriber will be able to monitor consumption of resources that are used by their servers totally and per each server. The following are recommended steps:

  1. Create a subscription for a customer and open the customer control panel.

  2. In the customer control panel, make sure the new subscription is selected in the Subscription drop-down box.

  3. Make sure, the VPS Management and Resource Usage tabs are available.

  4. Switch to the VPS Management tab and create a couple of VPSes with different configurations.

  5. Switch to the Resource Usage tab to monitor resource consumption. If the resource statistics is not collected yet, force the collection process as described in the following items.

    • In the provider CP, navigate to Operations > Tasks.
    • On the Periodic tab, find the Synchronize resource usage for instances of APS applications task.
    • Select the task and click Run Tasks.
    • Return back to the customer CP and refresh the screen.

    You should have a table displaying resource usage similar to the following:

    ../../../_images/pa-demo-counter-resources.png
  6. You can also verify total resource usage in the subscription by navigating to Home > Resource Usage.

    ../../../_images/pa-demo-counter-subscription-usage.png

This completes the APS application development cycle. If you experienced any issues when following the project steps, you can download the final package and compare it with the demo package you have created.