How to enable VM monitoring and metrics via API

Owned by MS (Unlicensed)
Feb 04, 2024
55 min read

Introduction

This page describes how to enable VM monitoring and metrics via API and select a set of metrics to fetch.

You will need the following resources.

  • A VM that is not deployed (or powered off)

    • This how-to uses an example VM that is not deployed

  • A monitoring server

Your user role must include the following privileges.

  • Manage virtual machine metrics → ROLE_USERS_ENABLE_DISABLE_VM_METRICS

  • Edit virtual appliance details → ROLE_VAPP_CUSTOMISE_SETTINGS

  • Manage virtual machine backup configuration (VAPP_MANAGE_BACKUP). This is because backups previously used metadata


Your user must be in the enterprise that owns the virtual datacenter and virtual resources.

The following pages describe Metrics configuration and UI functionality.

Summary diagram

The steps in this diagram link to the API reference guide resources and data entities sections.





Detailed steps

  1. Get VMs from the cloud

    1. Filter the VMs using the vmlabel query parameter, for example, to get a VM with a label value of "yVM1"

    2. Reference: https://wiki.abiquo.com/api/latest/AllVirtualMachinesResource.html#list-virtual-machines-of-the-user

    3. cURL

      GET all virtual machines in the cloud, filtering by label

      curl -X GET https://abiquo.example.com:443/api/cloud/virtualmachines?vmlabel=yVM1 \ -H "Accept: application/vnd.abiquo.virtualmachines+json; version=5.1" \ -u user:password --verbose | pjson



    4. Sample response. Success status code: 200
      Note: This request returns a collection of VMs

      { "totalSize": 1, "links": [ { "rel": "first", "href": "https://abiquo.example.com:443/api/cloud/virtualmachines?vmlabel=yVM1&limit=25&by=name&asc=true" }, { "rel": "last", "href": "https://abiquo.example.com:443/api/cloud/virtualmachines?vmlabel=yVM1&startwith=0&limit=25&by=name&asc=true" } ], "collection": [ { "id": 634, "uuid": "cc3f0803-1f42-4baa-9e66-d6a3af406d48", "description": "A virtual machine", "coresPerSocket": 1, "idState": 1, "idType": 0, "type": "MANAGED", "highDisponibility": 0, "monitored": false, "protected": false, "variables": {}, "backuppolicies": [], "generateGuestInitialPassword": false, "natrules": [], "vdrpEnabled": true, "vdrpPort": 0, "password": "ZtnIXKdA", "deallocated": false, "name": "ABQ_cc3f0803-1f42-4baa-9e66-d6a3af406d48", "label": "yVM1", "ram": 48, "cpu": 1, "state": "NOT_ALLOCATED", "creationTimestamp": 1608740019000, "links": [ { "title": "Abiquo", "rel": "enterprise", "type": "application/vnd.abiquo.enterprise+json", "href": "https://abiquo.example.com:443/api/admin/enterprises/1" }, { "title": "ABQ_cc3f0803-1f42-4baa-9e66-d6a3af406d48", "rel": "edit", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634" }, { "rel": "asynctasks", "type": "application/vnd.abiquo.asynctasks+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/asynctasks" }, { "title": "send mail", "rel": "sendmail", "type": "application/vnd.abiquo.mail+json", "href": "https://abiquo.example.com:443/api/admin/publiccloudregions/4/enterprises/1/virtualmachines/634/action/sendmail" }, { "title": "cloudadmin cloudadmin", "rel": "user", "type": "application/vnd.abiquo.user+json", "href": "https://abiquo.example.com:443/api/admin/enterprises/1/users/7" }, { "title": "vdc_vcenter", "rel": "virtualdatacenter", "type": "application/vnd.abiquo.virtualdatacenter+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35" }, { "title": "vpp_vcenter", "rel": "virtualappliance", "type": "application/vnd.abiquo.virtualappliance+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29" }, { "title": "metadata", "rel": "metadata", "type": "application/vnd.abiquo.metadata+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/metadata" }, { "title": "vlan network configurations", "rel": "configurations", "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/network/configurations" }, { "title": "nics", "rel": "nics", "type": "application/vnd.abiquo.nics+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/network/nics" }, { "title": "disks", "rel": "harddisks", "type": "application/vnd.abiquo.harddisks+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/storage/disks" }, { "title": "NOT_ALLOCATED", "rel": "state", "type": "application/vnd.abiquo.virtualmachinestate+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/state" }, { "title": "virtual machine undeploy", "rel": "undeploy", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/undeploy" }, { "title": "virtual machine deploy", "rel": "deploy", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/deploy" }, { "title": "virtual machine reset", "rel": "reset", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/reset" }, { "title": "virtual machine snapshot", "rel": "instance", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/instance" }, { "title": "remote access", "rel": "rdpaccess", "type": "application/vnd.abiquo.virtualmachineconsole+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/config/rdpaccess" }, { "title": "tasks", "rel": "tasks", "type": "application/vnd.abiquo.tasks+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tasks" }, { "title": "firewalls", "rel": "firewalls", "type": "application/vnd.abiquo.links+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/firewalls" }, { "title": "load balancers", "rel": "loadbalancers", "type": "application/vnd.abiquo.loadbalancers+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/loadbalancers" }, { "title": "request on demand backup", "rel": "requestbackup", "type": "application/vnd.abiquo.ondemandbackup+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/backup/action/request" }, { "title": "request a restore of a backup", "rel": "requestrestore", "type": "application/vnd.abiquo.restore+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/backup/action/restore" }, { "title": "move VM to a virtual appliance", "rel": "vappmove", "type": "application/vnd.abiquo.links+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/vappmove" }, { "title": "move VM to another virtual datacenter", "rel": "move", "type": "application/vnd.abiquo.movevm+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/move" }, { "title": "volumes", "rel": "volumes", "type": "application/vnd.abiquo.volumes+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/storage/volumes" }, { "diskControllerType": "IDE", "diskLabel": "Hard disk 1", "length": "64", "title": "e706ed17-b6e9-4c71-8291-1e9527c44a49", "rel": "disk0", "type": "application/vnd.abiquo.harddisk+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/disks/148" }, { "title": "dstiersharedds2", "rel": "datastoretier0", "type": "application/vnd.abiquo.datastoretier+json", "href": "https://abiquo.example.com:443/api/cloud/locations/4/datastoretiers/4" }, { "title": "protect", "rel": "protect", "type": "text/plain", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/protect" }, { "title": "unprotect", "rel": "unprotect", "type": "text/plain", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/unprotect" }, { "title": "metricsmetadata", "rel": "metricsmetadata", "type": "application/vnd.abiquo.metricsmetadata+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/metrics" }, { "title": "enablemonitoring", "rel": "enablemonitoring", "type": "", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/enablemonitoring" }, { "title": "collectd", "rel": "collectd", "type": "application/json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/metrics/collectd" }, { "title": "alarmssearch", "rel": "alarmssearch", "type": "application/vnd.abiquo.alarms+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/alarms" }, { "title": "clone", "rel": "clone", "type": "application/vnd.abiquo.virtualmachinecloneoptions+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/action/clone" }, { "rel": "tags", "type": "application/vnd.abiquo.resourcetags+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags" }, { "rel": "tags-update", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags" }, { "rel": "tags-format", "type": "application/vnd.abiquo.tagformatrestrictions+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags" }, { "rel": "tags-create", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags/action/create" }, { "rel": "tags-delete", "type": "application/vnd.abiquo.tagkeys+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags/action/delete" }, { "rel": "tags-edit", "type": "application/vnd.abiquo.tags+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags/action/edit" }, { "rel": "tags-sync", "type": "", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/tags/action/sync" }, { "title": "VMware vCenter", "rel": "hypervisortype", "type": "application/vnd.abiquo.hypervisortype+json", "href": "https://abiquo.example.com:443/api/config/hypervisortypes/VMX_04" }, { "title": "yVM", "rel": "virtualmachinetemplate", "type": "application/vnd.abiquo.virtualmachinetemplate+json", "href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/4/virtualmachinetemplates/151" }, { "title": "Others", "rel": "category", "type": "application/vnd.abiquo.category+json", "href": "https://abiquo.example.com:443/api/config/categories/1" } ], "usageStatistics": [] } ], "duplicatedvms": [] }



    5. Note that the "monitored" attribute has a value of false, which means do not fetch VM metrics

    6. Keep the VM entity to update it. You will also need the metricsmetadata, metadata, and enablemonitoring links

      1. Metricsmetadata link. From here you can obtain the metrics that are available for the VM

        { "title": "metricsmetadata", "rel": "metricsmetadata", "type": "application/vnd.abiquo.metricsmetadata+json", "href": "https://abiquo.example.com:443/api/cloud/virtualdatacenters/35/virtualappliances/29/virtualmachines/634/metrics" },



      2. Metadata link. You can use this link to define the metrics to retrieve



      3. Enable monitoring link



  2. Obtain the metrics available for the VM

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#list-metrics-metadata-on-a-virtual-machine

    2. cURL



    3. Sample response. Success status code: 200



    4. To define the metrics to enable, keep the metric names. 



  3. Get existing VM metadata

    1. When you write to metadata, you will overwrite all existing metadata. So always start with a GET request to retrieve the existing metadata to use as the base object for adding metadata.

    2. Reference: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#get-virtual-machine-metadata

    3. cURL



    4. Sample response. Success status code: 200. Note that the platform stores the VM startup script in metadata.



  4. Prepare a metadata object for monitoring and metrics

    1. Use the "monitoring-metrics" keyword and add the metrics to enable



  5. Update the VM metadata

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#update-virtual-machine-metadata

    2. cURL



    3. Request data for this request will be in the file named "virtualMachineMD.json".

    4. Sample response. Success status code: 200



  6. Enable monitoring and fetch metrics

    1. Reference: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#enable-fetch-of-metrics-for-a-virtual-machine

    2. cURL



    3. Success status code: 204 - No content


Now when you access the VM in the UI, you should see the metrics symbol on the VM icon.

And when you edit the VM on the Monitoring tab, the above metrics should be selected.

And if you deploy the VM and wait a little while, the platform should display the requested metrics!

Copyright © 2006-2024, Abiquo Holdings SL. All rights reserved