One of the most common questions I get from my Nutanix colleagues, as well as customers and partners, is “How do I use the Nutanix API to get VM performance statistics?” Before digging into exactly how we do that, let’s take a quick look at how things stand today.

And yes, I’m aware this blog hasn’t been updated in a very long time.

As of today, April 19th 2018, there are 4 versions of the Nutanix API that can be used. Which API you use will depend on the data you’re trying to get and where you’re trying to get it from.

Firstly, here are the 4 versions and an over-simplified idea of what you’d use them for.

Authentication

Before getting started, please be aware that all API examples below are carried out using HTTP Basic Authentication. This can be done by either logging into your Prism Element UI and then running the requests in a new browser tab, or by using a third-party application like Postman. I’d choose Postman every time, simply because of the vast array of options at your disposal.

API v0.8

This set of APIs was made available at a time when the v1 APIs (see below) didn’t have built-in functions for things like powering on a VM. Combined with the v1 APIs, nearly all information and functions available in Prism could be completed via API requests. The obvious disclaimer is that I said nearly …

Here’s an example of a very basic v0.8 API request to list all VMs on a cluster:

https://<cluster_virtual_ip>:9440/api/nutanix/v0.8/vms

API v1

This set of APIs, chronologically, was released before the v0.8 APIs. They were used, for example, to manipulate and view VMs, storage containers, storage pools etc. For some time, the v1 and v0.8 APIs were the only way we, as developers, had to interact with Nutanix clusters. Some of the API endpoints could only be used with the AHV hypervisor and some could be used across multiple hypervisors e.g. AHV and ESXi.

Here’s a simple example of a v1 API request to list all storage containers on a cluster:

https://<cluster_virtual_ip>:9440/PrismGateway/services/rest/v1/containers

API v2

The v0.8 and v1 APIs worked really well. In fact, they were (and still are, in many respects) how the Prism UI gathers data from the cluster. Another over-simplification would be to say that the v2 APIs are where the v0.8 and v1 APIs came together. Pretty much all of the entities and endpoints available in v0.8 and v1 were made available in v2, along with a huge amount of backend cleanup, endpoint renaming and generally making the APIs better. The v2 APIs are also the first officially GA API made available by Nutanix.

If you have some exposure to the previous v0.8 and v1 APIs, moving to the v2 APIs will highlight a number of differences. For example “containers” got renamed to “storage_containers” and “storagePools” got renamed to “storage_pools”. The difference? A consistent naming convention in the form of snake-case across all entities. This article isn’t a discussion about the benefits of snake- vs camel-case or anything like that, though …

Here’s a basic example of a v2 API request to list all storage_containers on a cluster:

https://<cluster_virtual_ip>:9440/api/nutanix/v2.0/storage_containers

Quick summary

Before moving forward, note that all the APIs above return what I’d consider pretty much industry-standard JSON data that is easily consumable by any programming or scripting language worth using. That was always the case and is still the case today. Easy!

All the requests above, by the way, are basic HTTP GET requests. There’s no POST body required for any of them. After all, we’re just GETting information, right?

API v3

Here’s where things get interesting. The v3 APIs, which went GA on April 17th 2018, are the first real departure from how things were done before.

Yes, we had standard GET requests to get data from a cluster and standard POST methods to make changes, but the v3 APIs are a bit different. All the previous APIs still required the developer to tell the system what to do and how to do it. The v3 APIs, on the other hand, are the first APIs built around an Intentful paradigm, that is, move the programming from the user to the machine. What does this mean? Instead of writing a ton of code to get something done, tell the system what your desired state is and the system will “figure out” the best way to get there. This will sound somewhat familiar to those using configuration management frameworks like Salt, Puppet, Chef, Ansible, PowerShell DSC etc.

How this all happens is somewhat beyond the scope of this particular article (I might cover it in another article at some point) but look at the request below. It’s still getting similar information as the previous requests but with a couple of differences.

It is an HTTP POST request, not GET.
A JSON POST body is required so that the cluster knows what type of entity to return. In this example, we’re talking about VMs.
We’re telling the system what we want to do with the data. In this case, we want to list all VMs.
While this request can be run without issue against Prism Element, it can also be run against Prism Central. More on that later.

https://<prism_central_or_cluster_virtual_ip>:9440/api/nutanix/v3/vms/list

And the POST body:

{&quot;kind&quot;:&quot;vm&quot;}

Wrapping up this part

At this point, you know what the available APIs versions are and what some of the differences are between them.

Now let’s move on what this lengthy article is actually about.

VM Performance Statistics

I’ll start this section by saying one important thing. The VM stats stuff below isn’t documented. This isn’t the appropriate location to talk about why this is or isn’t, but please be aware of it. You won’t find any info on VM performance statistics in the documentation or on the Nutanix Developer Portal.

Now, as you’re probably aware, Prism Element and Prism Central show an absolute ton of critically-important info re various entity types. VMs, storage containers, protection domains and the cluster(s) themselves. A lot of that is generated from the Nutanix APIs, including parts of the performance information.

To get performance information for a VM, you’ll need to know a few things:

The VM UUID. Using the API example above you’ll be able to get the UUID of the VM you want to work with.
The statistical interval you want to use: interval. E.g. do you want performance statistics for a VM every 30 seconds? Every 60 seconds?
The start time for the period you want to report on: startTimeInUsecs. This value must be in “usecs” i.e. the microseconds elapsed since Epoch/UNIX time began (Jan 1st, 1970). If you aren’t going to convert your dates and times programmatically, a good alternative is to use one of the many online converters. For example, EpochConverter. Remember to add the appropriate number of zeroes to convert the results from seconds to microseconds!
The end time for the period you want to report on: endTimeInUsecs. As with the start time, this value must be in “usecs”.
The metric you want to report on. Hang on … if none of this is documented, how do I know what metrics are available? If you use the v1 APIs to gather information on a specific VM, the available metrics are listed in the response! Sneaky, eh? For example, look at this request:

https://<prism_central_or_cluster_virtual_ip>:9440/api/nutanix/v1/vms/<vm_uuid>

Let’s take the output of that request and throw it into the brilliant JSON Editor Online (if you don’t use JSON Editor Online, you’re missing out).

Scrolling through the JSON that we got back from the request, we’ll see this:

Stats response - closed

And, if we open up the ‘stats’ section, we get this …

Stats response - open

Whoa. Look at all those metrics we can go through!

Seriously, though, each of those can be used as a parameter to our actual request for VM stats.

Let’s say we want to check out our VM’s hypervisor CPU usage. To explain each part of the request that’s coming up, here are the values we’ll use to construct our request:

VM UUID: 3aa1699a-ec41-4037-aade-c73a9d14ed8c (yours will be different)
Cluster virtual IP address: 10.133.16.50 (yours will probably be different)
Interval: every 30 seconds
Start time in usecs: 1524009660000000 (00:01:00 on April 18th 2018)
End time in usecs: 1524096060000000 (00:01:00 on April 19th 2018)
Metric: hypervisor_cpu_usage_ppm

Assuming we have our authentication sorted out (the chosen method is up to you – see above), we can construct a complete HTTP GET request for this. The complete request looks like this:

https://10.133.16.50:9440/api/nutanix/v1/vms/3aa1699a-ec41-4037-aade-c73a9d14ed8c/stats/?metrics=hypervisor_cpu_usage_ppm&startTimeInUsecs=1524009660000000&endTimeInUsecs=1524096060000000&interval=30

We requested stats every 30 seconds, which means we’ll get 2881 values in our response – we requested data for a specific 24 hour period. Each value represents the VM’s hypervisor CPU usage at that point in time.

Taking the entire response and processing it through JSON Editor Online allows us to easily see exactly what the response was:

Stats response - example

With this information, we can process it or report on it any way we choose. For example, we could use PHP, Python, PowerShell or any other scripting/programming language of our choice to do something with that data.

From here’s it’s up to you what you do with it.

Prism Element “vs” Prism Central

If you take some time to look through the Nutanix Developer Portal, you’ll see the v3 APIs are broken into two distinct sections: Prism Element and Prism Central.

With the introduction of features and products like Nutanix Calm and Microsegmentation, the entities you interact with will be different depending on where you’re sending the request.

For example, the v3 APIs can be used to talk to Prism Element. Prism Element is the graphical management UI that runs on each individual cluster. While Prism Element can be registered against Prism Central for various reasons, it isn’t mandatory (although it’s a very good idea, these days). For that reason, the endpoints available in the Prism Element v3 APIs are different from those available in the Prism Central APIs:

VMs
- Available in both Prism Element and Prism Central
Images
- Available in both Prism Element and Prism Central
Blueprints
- Available in Prism Central only
Apps
- Available in Prism Central only
Storage containers
- Available in Prism Element only

The recommendation here is to make sure you do read through the Nutanix Developer Portal. This will help you to make sure you are trying to access endpoints exposed by the correct service and that you know which endpoints are available to you.

Hope this extended article helps.

The post VM Performance Stats with Nutanix REST API appeared first on DigitalFormula.