• Improve this Doc

    Show / Hide Table of Contents

    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.

    1. Log in to the Cloud Director API.

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

    2. 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
      
    3. 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.

    1. Log in to the Cloud Director API.

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

    2. 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
      
    3. 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.

    ☀
    ☾
    Generated by DocFX
    Back to top
    © UKCloud Ltd, 2022. All Rights Reserved.
    Privacy Policy. Terms of Use. Contribute.

    The UKCloud Knowledge Centre uses cookies to ensure that we give you the best experience on our website. If you continue we assume that you consent to receive all cookies on this website.