Usage component generates statistics for various usage types. These statistics can be translated to the end user billing details depending on the customer billing criteria.
 

Usage types:

• Allocated VM
• Running VM

• Public IP address

• Network - Bytes sent, Bytes received

• Volume

• Secondary Storage

• Template

• ISO

• Snapshot

• Port Forwarding

• Load Balancer Policies

• Network Offering
• VPN Users 

Configuration

ParameterDescriptionDefault| usage.stats.job.aggregation.range | Usage is aggregated for specified number of minutes. e.g 1440 for daily aggregation | 1440 |

Usage Server

Usage Server runs as a separate component. Usage Server schedules a job at the time specified by usage.stats.job.exec.time parameter. This job will query the cloud DB usage_events table and generates usage records.
Broadly usage generation sequence is as follows:

• Event logged into cloud.usage_event table
• Get a list of the latest usage events
• Insert the latest usage events into the cloud_usage.usage_events table
• Helper tables populated from cloud_usage.usage_event table after parsing
• cloud_usage.cloud_usage table populated with aggregation range wise data. Helper table data is used here.
   
  Currently there is no UI which displays usage records. API call listUsageRecords fetches usage records.
   
  Sample record in cloud_usage.cloud_usage table
   
  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  | id | zone_id | account_id | domain_id | description                                              | usage_display | usage_type | raw_usage         | vm_instance_id | vm_name  | offering_id | template_id | usage_id | type | size | start_date          | end_date            |
  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  |  5 |       1 |          2 |         1 | i-2-3-KK running time (ServiceOffering: 7) (Template: 2) | 0.138058 Hrs  |          1 | 0.13805645644456 |              3 | i-2-3-KK |           7 |           2 |        3 | NULL | NULL | 2011-02-09 09:36:00 | 2011-02-09 09:47:00 |
  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   
   

Usage Type and ID mapping:

 
UsageTypes can be obtained using the listUsageTypes API.
 

Allocated VM

Every time a VM is created VM.CREATE event is logged. Similarly VM.DESTROY event is logged when VM is destroyed. Corresponding entries in cloud.usage_event table would like the following:
 
+------------------------------------------------------------------------------------------------------------+
| id | type | account_id | created | zone_id | resource_id | resource_name | offering_id | template_id | size | processed |
+------------------------------------------------------------------------------------------------------------+
| 11 | VM.CREATE | 2 | 2011-02-09 11:15:27 | 1 | 5 | i-2-5-KK | 7 | 2 | NULL | 0 |
| 12 | VM.DESTROY | 2 | 2011-03-09 10:16:18 | 1 | 5 | i-2-5-KK | 7 | 2 | NULL | 0 |
+------------------------------------------------------------------------------------------------------------+
 
Duration between VM.CREATE and VM.DESTROY is reported as Allocated VM usage

Running VM

Usage for Running VM is implemented similar to allocated VM usage. Events VM.start and VM.stop are tracked here instead.
 
+-----------------------------------------------------------------------------------------------------------+
| id | type     | account_id | created             | zone_id | resource_id | resource_name | offering_id | template_id | size | processed |
+-----------------------------------------------------------------------------------------------------------+
| 12 | VM.START |          2 | 2011-02-09 11:16:18 |       1 |           5 | i-2-5-KK      |           7 |           2 | NULL |         0 |
| 15 | VM.STOP  |          2 | 2011-02-09 12:00:24 |       1 |           5 | i-2-5-KK      |           7 |           2 | NULL |         0 |
+-----------------------------------------------------------------------------------------------------------+
 
Duration between VM.START and VM.STOP is reported as Running VM usage 

Public IP address

NET.IPASSIGN, NET.IPRELEASE events are tracked here. Sample IPASSIGN and RELEASE event entries are as follows:
+---------------------------------------------------------------------------------------------------------------+
| id | type         | account_id | created             | zone_id | resource_id | resource_name | offering_id | template_id | size | processed |
+---------------------------------------------------------------------------------------------------------------+
|  2 | NET.IPASSIGN |          2 | 2011-02-09 09:32:54 |       1 |          10 | 10.91.30.129  |        NULL |        NULL |    1 |         0 |
|  9 | NET.RELEASE |          2 | 2011-02-09 11:15:27 |       1 |          21 | 10.91.30.250  |        NULL |        NULL |    0 |         0 |
+---------------------------------------------------------------------------------------------------------------+
 

Network Usage

cloud.user_statistics is queried and populated to cloud_usage.user_statistics with latest stats. Network helper entry is created in usage_network table. Network usage for current event is calculated as:
bytesSent = (total bytes sent) – (bytes sent prior to this event);
bytesReceived = (total bytes received) – (bytes received prior to this event);
Usage entry is created by querying usage_network table for all entries with event_time in the given range.
 type
 
Network usage is processed differently and is not driven by usage events. In Virtual Networking case Iptables rules are set in domR to track public traffic.
Iptables rules are as follows:
     iptables -A NETWORK_STATS -i eth0 -o eth2
     iptables -A NETWORK_STATS -i eth2 -o eth0
     iptables -A NETWORK_STATS -o eth2 ! -i eth0 -p tcp
     iptables -A NETWORK_STATS -i eth2 ! -o eth0 -p tcp
 
Similar rules will be added if there are multiple public interfaces. 
Management server queries  for these stats periodically and populates them in user_statistics table account-wise. router.stats.interval parameter defines the frequency to fetch these stats. Stats received are cumulative and are stored in current_bytes_received and current_bytes_sent columns. Iptable counters are reset when the domR restarts. Upon a restart, current_bytes in user_statistics table are moved to net_bytes columns. A diff of total usage (current_bytes + net_bytes) in previous aggregation period and current period will give the network usage.

agg_bytes = current_bytes + net_bytes

Only Isolated network usage is tracked by VR

Usage metering for direct network is done using "Traffic Sentinel"

Usage metering for Direct Network

Volume

VOLUME.CREATE and VOLUME.DELETE events are tracked here. Every time a VM is created a ROOT volume gets created along with any additional DATA volumes with the selected disk offering. VOLUME.CREATE event is logged when either a volume is created separately or during the process of VM creation. 
 
+----------------------------------------------------------------------------------------------------------------------+
| id | type          | account_id | created             | zone_id | resource_id | resource_name | offering_id | template_id | size       | processed |
+----------------------------------------------------------------------------------------------------------------------+
| 10 | VOLUME.CREATE |          2 | 2011-02-09 11:15:27 |       1 |           5 | ROOT-5        |        NULL |           2 | 8589934592 |         0 |
| 18 | VOLUME.DELETE |          2 | 2011-02-09 12:00:25 |       1 |           5 | ROOT-5        |        NULL |        NULL |       NULL |         0 |
+----------------------------------------------------------------------------------------------------------------------+
 
 

Template

TEMPLATE.CREATE and TEMPLATE.DELETE events are tracked here. 
 
+------------------------------------------------------------------------------------------------------------------------------------+
| id | type            | account_id | created             | zone_id | resource_id | resource_name             | offering_id | template_id | size       | processed |
+------------------------------------------------------------------------------------------------------------------------------------+
|  1 | TEMPLATE.CREATE |          2 | 2011-02-09 09:31:37 |       1 |           2 | CentOS 5.3(x86_64) no GUI |        NULL |        NULL | 8589934592 |         0 |
| 18 | TEMPLATE.DELETE   |          2 | 2011-02-09 12:00:25 |       1 |           2 | NULL                    |        NULL |        NULL |       NULL |         0 |
+------------------------------------------------------------------------------------------------------------------------------------+
 
 

ISO

ISO.CREATE and ISO.DELETE events are tracked here. 
 
+------------------------------------------------------------------------------------------------------------------------------------+
| id | type            | account_id | created             | zone_id | resource_id | resource_name             | offering_id | template_id | size       | processed |
+------------------------------------------------------------------------------------------------------------------------------------+
|  11 | ISO.CREATE |          2 | 2011-02-11 07:31:37 |       1 |           3 | myISO |        NULL |        NULL | 34545556592 |         0 |
| 14 | ISO.DELETE   |          2 | 2011-02-12 09:00:25 |       1 |           3 | NULL                    |        NULL |        NULL |       NULL |         0 |
+------------------------------------------------------------------------------------------------------------------------------------+
 
 

SNAPSHOTS

SNAPSHOT.CREATE and SNAPSHOT.DELETE events are tracked here. 
 
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| id | type            | account_id | created             | zone_id | resource_id | resource_name                                         | offering_id | template_id | size       | resource_type | processed |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| 74 | SNAPSHOT.CREATE |          2 | 2012-02-09 07:21:16 |       1 |          16 | v_20120209072115 |        NULL |        NULL | 1073741824 | NULL          |         0 |
| 73 | SNAPSHOT.DELETE |          2 | 2012-02-09 07:21:16 |       1 |          15 | v_20120208182211 |        NULL |        NULL |          0 | NULL          |         0 |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
 
 

Usage Events

 
Usage events are stored usage_event table. Any resource for which usage has to be tracked needs to log usage events when the the resource is created/allocated and when its deleted/released. Network usage is the only exception which doesn't use usage events. Once these events are logged usage server will process them and generate usage records.
 
Description of various columns in usage_event table:
 
type - Event type as described in cloudstack-oss/api/src/com/cloud/event/EventTypes.java
account_id - Id of the account which owns the resource
zone_id - Data center to which this resource belongs to
resource_id - Id of the resource. For VM usage this will be VmId, for template templateId etc
resource_name - Name of the resource.
offering_id - Id of Service Offering in case of Vm usage, Disk offering in case of volume usage etc..
template_id - Id of the template used for a volume / Vm. 
size - Size of the resource. Volume Size or Template size etc.
resource_type - Additional type attribute for a resource. Could be used for hypervisor_type etc.
processed - Is set to 0 by default. This field is updated to 1 when the usage server completes processing of this event.
 

listUsageRecords API

Response Tags by usage type

1. RUNNING_VM / 2. ALLOCATED_VM

Response NameDescription

3. IP_ADDRESS

Response NameDescription

4. NETWORK_BYTES_SENT / 5. NETWORK_BYTES_RECEIVED

Response NameDescription

6. Volume

Response NameDescription

7. Template

Response NameDescription

8. ISO

Response NameDescription

9. Snapshot

Response NameDescription

11. Load Balancer Policy

Response NameDescription

12. Port Forwarding

Response NameDescription

13. Network Offering

Response NameDescription

14. VPN Users

Response NameDescription

Running usage server is Dev setup

mvn -P usage -Drun -Dpid=1234