To retrieve a subset of current or historic metrics, make a POST request to a current or historic metrics URL. The request body specifies the metrics you want.

The vCloud API defines two request bodies, CurrentUsageSpec and HistoricUsageSpec, that you can use to constrain a metrics request to a subset of available metrics. With these request bodies, you can specify metrics by name, or supply a pattern that uses a wildcard to match a set of names. You can also specify a collection interval for historic metrics. See Metric Names and Patterns.

Prerequisites

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

Procedure
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 where rel="metrics".

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

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

Create the appropriate request body.

The request body specifies the metrics you want.

Option

Request

Retrieve a subset of current metrics

Create a CurrentUsageSpec element to use as the request body.

Retrieve a subset of historic metrics

Create a HistoricUsageSpec element to use as the request body.
4

POST the request body to the appropriate metrics link.

See Example: Retrieving a Subset of Current or Historic Metrics

Note

If you do not include a request body, the request is processed as though you had made a GET request.

Example: Retrieving a Subset of Current or Historic Metrics

This example uses a POST request with a CurrentUsageSpec body to request a subset of the current metrics retrieved in Example: Retrieving All Current or Historic Metrics. This example also shows the use of wildcards in a MetricPattern element. See Metric Patterns.

Request 

POST https://vcloud.example.com/api/vApp/vm-4/metrics/current
Content-type: application/vnd.vmware.vcloud.metrics.currentUsageSpec+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CurrentUsageSpec xmlns="http://www.vmware.com/vcloud/v1.5">
   <MetricPattern>*.average</MetricPattern>
</CurrentUsageSpec>

Response 

200 OK
Content-Type: application/vnd.vmware.vcloud.metrics.currentusage+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CurrentUsage
   xmlns="http://www.vmware.com/vcloud/v1.5">
   <Link
      rel="up"
      href="https://vcloud.example.com/api/vApp/vm-4f"
      type="application/vnd.vmware.vcloud.vm+xml"/>
   <Metric
      name="cpu.usage.average"
      unit="PERCENT"
      value="5.36"/>
   <Metric
      name="cpu.usagemhz.average"
      unit="MEGAHERTZ"
      value="112.0"/>
   <Metric
      name="mem.usage.average"
      unit="PERCENT"
      value="2.99"/>
   <Metric
      name="disk.write.average"
      unit="KILOBYTES_PER_SECOND"
      value="0.0"/>
   <Metric
      name="disk.read.average"
      unit="KILOBYTES_PER_SECOND"
      value="0.0"/>
</CurrentUsage>

This example uses a POST request with a HistoricUsageSpec body to request a subset of the historic metrics retrieved in Example: Retrieving All Current or Historic Metrics. This example also shows the use of wildcards and a time specification for the past 8 hours.

Request 

POST https://vcloud.example.com/api/vApp/vm-4/metrics/historic
Content-type: application/vnd.vmware.vcloud.metrics.historicUsageSpec+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<HistoricUsageSpec xmlns="http://www.vmware.com/vcloud/v1.5">
   <RelativeStartTime
      interval="8"
      unit="hour"/>
   <RelativeEndTime
      interval="0"
      unit="hour"/>
   <MetricPattern>cpu.*</MetricPattern>
   <MetricPattern>disk.*</MetricPattern>
</HistoricUsageSpec>

The full response contains several thousand lines, so only a subset appears here.

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>