Retrieving Metrics Subsets

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 VMware Cloud Director 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

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

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.

POST the request body to the appropriate metrics link.
See 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 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 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>