How to retrieve utilisation metrics for your virtual machines

Overview

You can use the Cloud Director API to retrieve current or historic utilisation metrics for a virtual machine (VM). You can retrieve the following utilisation metrics:

Average CPU usage (%)
Maximum CPU usage (%)
Average CPU usage (MHz)
Average memory usage (%)
Average disk write speed (KBps)
Average disk read speed (KBps)
Amount of disk provisioned (KB)
Amount of disk used (KB)

You can retrieve current and historic utilisation metrics for VMs in all UKCloud regions.

Note

You can also find utilisation metrics for a VM in VMware Cloud Director by selecting Details and expanding the Monitoring Chart section.

Intended audience

To retrieve the utilisation metrics using the API, you must be logged into the Cloud Director API as an administrator, Catalog Author or vApp Author.

Retrieving current utilisation metrics

Current metrics are values collected at the time the request is processed by the server. You can use the Cloud Director API to retrieve a list of current metric values, one for each category.

You can retrieve current utilisation metrics for VMs in all regions.

Log in to the Cloud Director API.

For more information, see How to access VMware Cloud Director through the Cloud Director API.

Send the following request to the Cloud Director API to retrieve the current utilisation metrics for the VM.

GET https://<vcloud_api_url>/api/vApp/<vm_id>/metrics/current

Parameter	Description	Example
`vcloud_api_url`	The URL you use to access the Cloud Director API	`vcd.portal.skyscapecloud.com`
`vm_id`	The GUID of the VM for which you want to retrieve utilisation metrics You can find the GUID of the VM using the API or at the end of the URL in the VM details page in VMware Cloud Director	`vm-12345678-aaaa-bbbb-cccc-1234567890ab`

For example:

GET https://vcd.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab/metrics/current

The Cloud Director API response includes each of the current metric values, for example:

<CurrentUsage xmlns="http://www.vmware.com/vcloud/v1.5" ...>

    <Link
        rel="up"
        href="https://vcd.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab"
        type="application/vnd.vmware.vcloud.vm+xml">

    <Metric name="cpu.usage.average"
        unit="PERCENT"
        value="0.1"/>
    <Metric name="cpu.usage.maximum"
        unit="PERCENT"
        value="0.1"/>
    <Metric name="cpu.usagemhz.average"
        unit="MEGAHERTZ"
        value="2.0"/>
    <Metric name="mem.usage.average"
        unit="PERCENT"
        value="0.0"/>
    <Metric name="disk.write.average"
        unit="KILOBYTES_PER_SECOND"
        value="0.0"/>
    <Metric name="disk.read.average"
        unit="KILOBYTES_PER_SECOND"
        value="0.0"/>
    <Metric name="disk.provisioned.latest"
        unit="KILOBYTE"
        value="45410433"/>
    <Metric name="disk.used.latest"
        unit="KILOBYTE"
        value="111744.0"/>
</CurrentUsage>

Curl example

curl -i -XGET -H 'Accept: application/*+xml;version=34.0' -H 'x-vcloud-authorization: 1234567890abcdef1234567890abcdef' https://vcd.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab/metrics/current

Retrieving historic utilisation metrics

Historic metrics are collected and stored for three months. You can retrieve historic metrics for the last 24 hours of metric history.

You can retrieve historic utilisation metrics for VMs in all regions.

Log in to the Cloud Director API.

For more information, see How to access VMware Cloud Director through the Cloud Director API.

Send the following request to the Cloud Director API to retrieve the historic utilisation metrics for the VM.

GET https://<vcloud_api_url>/api/vApp/<vm_id>/metrics/historic

Parameter	Description	Example
`vcloud_api_url`	The URL you use to access the Cloud Director API	`vcd.pod0000b.sys00005.portal.skyscapecloud.com`
`vm_id`	The GUID of the VM for which you want to retrieve utilisation metrics You can find the GUID of the VM using the API or at the end of the URL in the VM details page in VMware Cloud Director	`vm-12345678-aaaa-bbbb-cccc-1234567890ab`

For example:

GET https://vcd.pod0000b.sys00005.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab/metrics/historic

The Cloud Director API response includes historic metric values for the last 24 hours, for example:

<HistoricUsage xmlns="http://www.vmware.com/vcloud/v1.5" ...>

    <Link
        rel="up"
        href="https://vcd.pod0000b.sys00005.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab"
        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"/>
        <Sample ... />
    </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"/>
        <Sample ... />
    </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/>

Curl example

curl -i -XGET -H 'Accept: application/*+xml;version=34.0' -H 'x-vcloud-authorization: 1234567890abcdef1234567890abcdef' https://vcd.pod0000b.sys00005.portal.skyscapecloud.com/api/vApp/vm-12345678-aaaa-bbbb-cccc-1234567890ab/metrics/historic

Feedback

If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to feedback@ukcloud.com.