Retrieving All Current or Historic Metrics

You can make a GET request to either of the metrics links in a Vm object to retrieve all current or historic metrics.

Current metrics are instantaneous values collected at the time the request is processed by the server. A GET request for current metrics retrieves a list of current metric values, one for each category, and returns it as a single XML document. You can retrieve a subset of current metrics by making a POST request with a CurrentUsageSpec body.

Historic metrics are collected and stored for 14 days. A GET request for historic metrics retrieves the past 24 hours of metric history and returns it as a single XML document. In the typical case, this document contains thousands of lines. You can retrieve a subset of historic metrics by making a POST request with a HistoricUsageSpec body.

Prerequisites

This operation requires the rights included in the predefined vApp User role or an equivalent set of rights.

See "Install and Configure Optional Database Software to Store and Retrieve Historic Virtual Machine Performance Metrics" in the vCloud Director Installation and Upgrade Guide for information about configuring the system to collect rolled-up metrics for VDCs and organisations.

Procedure

Retrieve the XML representation of the virtual machine.

Use a request like this one:

GET https://vcloud.example.com/api/vApp/vm-4

Examine the Vm element to find the metrics links that it contains.

These links have the following form, where id is the virtual machine's unique identifier:

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

Make a GET request to the appropriate link.

Option	Request
Retrieve all current metrics	GET https://vcloud.example.com/api/vApp/vm-`id/`metrics/current
Retrieve all historic metrics for the past 24 hours	GET https://vcloud.example.com/api/vApp/vm-`id/`metrics/historic

See Example: Retrieving All Current or Historic Metrics

Example: Retrieving All Current or Historic Metrics

This request retrieves all current metrics from a virtual machine.

Request

GET https://vcloud.example.com/api/vApp/vm-4/metrics/current

Response

200 OK
Content-Type: application/vnd.vmware.vcloud.metrics.currentusage+xml
...
<CurrentUsage 
   xmlns="http://www.vmware.com/vcloud/v1.5"
   ... >
   <Link
      rel="up"
      href="https://vcloud.example.com/api/vApp/vm-4"
      type="application/vnd.vmware.vcloud.vm+xml"/>
   <Metric
      name="cpu.usage.average"
      unit="PERCENT"
      value="33.7"/>
   <Metric
      name="cpu.usage.maximum"
      unit="PERCENT"
      value="89.0"/>
   <Metric
      name="cpu.usagemhz.average"
      unit="MEGAHERTZ"
      value="262.0"/>
   <Metric
      name="mem.usage.average"
      unit="PERCENT"
      value="44.0"/>
   <Metric
      name="disk.provisioned.latest"
      unit="KILOBYTE"
      value="2190418.0"/>
   <Metric
      name="disk.write.average"
      unit="KILOBYTES_PER_SECOND"
      value="20.0"/>
   <Metric
      name="disk.used.latest"
      unit="KILOBYTE"
      value="1633362.0"/>
   <Metric
      name="disk.read.average.0"
      unit="KILOBYTES_PER_SECOND"
      value="44.0"/>
   <Metric
      name="disk.read.average"
      unit="KILOBYTES_PER_SECOND"
      value="44.0"/>
</CurrentUsage>

This request retrieves the past 24 hours of metrics from a virtual machine. The typical response contains thousands of lines, so only a subset appears here.

Request

GET https://vcloud.example.com/api/vApp/vm-4/metrics/historic

Response

200 OK
Content-Type: application/vnd.vmware.vcloud.metrics.historicusage+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<HistoricUsage xmlns="http://www.vmware.com/vcloud/v1.5">
   <Link
      rel="up"
      href="https://vcloud.example.com/api/vApp/vm-4"
      type="application/vnd.vmware.vcloud.vm+xml"/>
   <MetricSeries
      expectedInterval="1800"
      name="disk.provisioned.latest"
      unit="KILOBYTE">
      <Sample
         timestamp="2013-12-02T20:00:00.000Z"
         value="875295.0"/>
      <Sample
         timestamp="2013-12-02T20:30:00.000Z"
         value="741388.0"/>
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="cpu.usagemhz.average"
      unit="MEGAHERTZ">
      <Sample
         timestamp="2013-12-02T20:03:20.000Z"
         value="505.0"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="122.93333333333334"/>
      <Sample ... />
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="disk.read.average"
      unit="KILOBYTES_PER_SECOND">
      <Sample
         timestamp="2013-12-02T20:03:20.000Z"
         value="208.7"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="0.0"/>
      <Sample ... />
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="mem.usage.average"
      unit="PERCENT">
      <Sample
         timestamp="2013-12-02T20:03:00.000Z"
         value="55.26272895119407"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="47.19066823323568"/>
      <Sample ... />
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="cpu.usage.average"
      unit="PERCENT">
      <Sample
         timestamp="2013-12-02T20:03:20.000Z"
         value="24.07100028991699"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="5.87066666285197"/>
      <Sample ... />
   </MetricSeries>
   <MetricSeries
      expectedInterval="1800"
      name="disk.used.latest"
      unit="KILOBYTE">
      <Sample
         timestamp="2013-12-02T20:00:00.000Z"
         value="262154.0"/>
      <Sample
         timestamp="2013-12-02T20:30:00.000Z"
         value="373779.0"/>
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="disk.write.average"
      unit="KILOBYTES_PER_SECOND">
      <Sample
         timestamp="2013-12-02T20:03:20.000Z"
         value="30.3"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="0.5333333333333333"/>
      <Sample ... />
   </MetricSeries>
   <MetricSeries
      expectedInterval="300"
      name="cpu.usage.maximum"
      unit="PERCENT">
      <Sample
         timestamp="2013-12-02T20:03:20.000Z"
         value="24.07100028991699"/>
      <Sample
         timestamp="2013-12-02T20:06:40.000Z"
         value="5.87066666285197"/>
      <Sample ... />
   </MetricSeries>
</HistoricUsage>

Note

In a system configured for rolled-up metrics collection, Org and Vdc elements include links you can use to retrieve cumulative metrics for VMs in all vApps in a VDC or in all VDCs in an organization. Requests to these links take the same form as requests shown in these examples, but return the total, for all VMs in all vApps in the container, for each metric subset.