Virtual machine metrics provide information about a virtual machine's performance and resource consumption in several categories.

vCloud Director collects metrics for all running virtual machines. You can retrieve virtual machine metrics either as an instantaneous reading taken when the request is made, or as a collection of historic readings taken at regular intervals. Historic metrics are retained for 14 days, and can be retrieved whether or not the virtual machine is powered on.

The following categories of metrics are collected:

cpu

Virtual CPU usage metrics. CPU metrics are an aggregate of all the virtual machine's cores and sockets.

disk

Virtual hard disk capacity and performance metrics. When a virtual machine has multiple disks, metrics are reported as an aggregate for all disks.

mem

Virtual machine memory usage.

For historic and current metrics, you can make a GET request to retrieve all categories of metrics from a virtual machine. A GET request for historic metrics returns only the most recent 24 hours of metric data samples. You can also make a POST request with a body that constrains the response to a subset of current or historic metrics in any or all categories. A POST request for historic metrics can specify a time period of up to 14 days.

Important

To support retrieval of historic metrics, vCloud Director must be configured with additional database software dedicated to historic metrics collection. See the vCloud Director Installation and Upgrade Guide.

Metrics Links in a Vm Element

When a virtual machine is powered on, the Vm element that represents it includes four links where the value of the type attribute has the form application/vnd.vmware.vcloud.metrics.*UsageSpec.xml. 

<Vm ... >
   ...
   <Link
      rel="down"
      href="https://vcloud.example.com/api/vApp/vm-4/metrics/current"
      type="application/vnd.vmware.vcloud.metrics.currentUsageSpec+xml"/>
   <Link
      rel="down"
      href="https://vcloud.example.com/api/vApp/vm-4/metrics/historic"
      type="application/vnd.vmware.vcloud.metrics.historicUsageSpec+xml"/>
   <Link
      rel="metrics"
      href="https://vcloud.example.com/api/vApp/vm-4/metrics/current"
      type="application/vnd.vmware.vcloud.metrics.currentUsageSpec+xml"/>
   <Link
      rel="metrics"
      href="https://vcloud.example.com/api/vApp/vm-4/metrics/historic"
      type="application/vnd.vmware.vcloud.metrics.historicUsageSpec+xml"/>
   ...
</Vm>

■

Use the links where rel="down" with a GET request to retrieve current or historic metrics in all categories.

■

Use the links where rel="metrics" with a POST request to retrieve a subset of current or historic metrics.

When a virtual machine is powered off, you cannot retrieve current metrics from it, so the .../metrics/current links are not returned in the Vm element.

Negative Values for Current Metrics

Current metrics can be returned with negative values if the specific metric being requested does not have a valid current value. This condition can exist if you make a metrics request before the first collection interval for that metric elapses. For example, a request for CPU usage metrics made shortly after a virtual machine is powered on can report negative values.

Subtopics