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.

Verify that you are logged in to the vCloud API as an administrator, Catalog Author, or vApp Author.

1

Retrieve the XML representation of the virtual machine.

Use a request like this one:

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

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"/>
3

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

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>