vROps / How to use the REST API to gather a metric’s configuration details

Share Button

Really recently, I discussed with a customer which is planning to use, for very specific usecases, vROps 6.

I am confident he will achieve what his customer is expecting from him. No doubt on this. By the way, my hands-on experience on vROps 6 told me that, while (over-)achieving your targets with vROps will undoubtfully be done, I also learnt that you may loose many times to just find the right metric for the right purpose.
I had the opportunity as well to work on this with a french TAM colleague (I will get his authorization before naming him here) who had to prepare these informations for a customer.

Previously, I wrote an article about building an XML file to automatically configure dashboards to a predefined standardized view (Please review : this article in case you haven’t read it already and/or are new to this topic).

1. What is the target of this article ?

I usually use this paragrah (only 1 or 2 sentences commonly) to avoid frustation while you read this post and to prevent loosing your time if you felt here by any mysterious error.

So, in this article, I will detail to leverage the REST API of vROps (vRealize Operations) version 6.0 and 6.1. It should be applicable to “near future” versions of vROps. However, the capture you’ll find below are taken from a vROps 6.??? appliance.

2. REST API ??

An API is a way to interact with a platform using a “standardized” speech.

REST stands for REpresentational State Transfer. This “language” is used by most of the platform nowadays to allow interaction with multiple form of components (script, programs, applications, bot and … human).
REST API allow you to submit, using HTTP(S), a query to a server and get a result, in different form (XML, JSON, …).

vROps can interact with environment using its REST API.

3. What you need

All you need is :

  • a vRealize Operations v6.0 (at least) instance
  • a REST client (could be JAVA, Ruby, Python, … well whatever suits your feeling). I personally use Chrome Advanced Rest Client (and all capture below will use it)
  • An user account that is “REST API authorized”. Check your user in the vROps interface to confirm the account is permitted to use REST API (not the admin UI but the “standard” UI).
  • Patience. If you are new to REST API, believe me, you’ll need some :), but this guide will definitely reduce this requirement at the minimum required.
  • and love (but I digress)

4. First calls

After connecting to your Chrome REST Client, you will be presented with a page expecting some inputs. Please see below.

20151126-vROps_REST_01-S001

In this example, I am requesting all the Adapter Kinds that my vROps instance knows. This is quite a simple example : I only used the query “GET /api/adapterkinds”. Please note that you will always have to start your URL query with “/suite-api”.

In the result section, you will find a result similar to this :

20151126-vROps_REST_01-S002

I manually collapsed every subtree to avoid overwhelming the page with to much useless details.

By the way, starting with this page, you can learn that this vROps instance is able to connect with different types of datasources :

  • Brocade Fabric Manager
  • Amazon AWS
  • NSX
  • VMware (really ;)) <= by the way, this one is really useful (obvious) for all datas for vSphere platforms noticeably
  • LogInsight
  • many more

The other interesting thing is the “Key” that you have to use to get more details.

Using the request “GET /api/adapterkinds” is the starting point I would recommend as every XML file will require it to understand your request. Remember that, in the heading of the XML file, you MUST specify the “AdapterKindKey”.

5. Let’s build an XML with the API

5.1 Start with the Adapter

Let’s start building an XML file that will be usable later in a dashboard. Below, we will use vSphere standard counters (but I will give examples of other adapters). So, it starts like this :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Used for Operations & Monitoring purposes -->
<!-- Applies to Widget type "Scoreboard" -->
<AdapterKinds>
</AdapterKinds>
</xml>

 

In the previous step, we identified that an Adapter Key is “VMWARE” (which is the one used by vSphere objects (VMs, clusters, …)). So, we can add a new statement in our XML file :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Used for Operations & Monitoring purposes -->
<!-- Applies to Widget type "Scoreboard" -->
  <AdapterKinds>
      <AdapterKind adapterKindKey="VMWARE">
      </AdapterKind>
  </AdapterKinds>
</xml>

 

5.2 Get the different objects

Let’s suppose we want to work on VMs in this XML file. We need to get the Resource key associated with these objects.
There’s a call for that :

20151126-vROps_REST_01-S003

Using REST call “GET /api/adapterkinds/VMWARE”, we have the following result :

20151126-vROps_REST_01-S004

As it is shown in the screenshot, the exact name we need to use is “VirtualMachine” (yes, so much surprise :)). Let’s add this information to our XML file :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Used for Operations & Monitoring purposes -->
<!-- Applies to Widget type "Scoreboard" -->
  <AdapterKinds>
   <AdapterKind adapterKindKey="VMWARE">
     <ResourceKind resourceKindKey="VirtualMachine">
     </ResourceKind>
   </AdapterKind>
  </AdapterKinds>
</xml>

 

What’s interesting in this capture, is the exact list and names of the different objects the VMWARE adapter is able to interact with. Following the same, you could be able to define a very complex dashboard to give as much input as you can to your user.

5.3 Add the metrics

Now, our XML can target a specific resource. We now need to determine the different metric that can be monitored using this object “VMWARE/VirtualMachine”. As you guessed, there’s a REST call for that as well, to name it “GET /api/adapterkinds/VMWARE/resourcekinds/VirtualMachine/statkeys”.

20151126-vROps_REST_01-S005

You will have the following result :

20151126-vROps_REST_01-S006

As you can see, you obtain numerous results. I identified an example of metric that can be used but you will need to browse the result to look for the specific metric you may require. Let’s finalize the XML sheet with some metrics taken from this result :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- Used for Operations & Monitoring purposes -->
<!-- Applies to Widget type "Scoreboard" -->
  <AdapterKinds>
    <AdapterKind adapterKindKey="VMWARE">
      <ResourceKind resourceKindKey="VirtualMachine">
        <Metric attrkey="config|hardware|num_Cpu" label="Number of vCPU" unit="vCPU(s)" />
        <Metric attrkey="cpu|readyPct" label="%tage of CPU Ready" unit="%" />
      </ResourceKind>
    </AdapterKind>
  </AdapterKinds>
</xml>

 

6. The step beyond

As I wrote previously, I have the opportunity to use a platform that can leverage multiple different solutions, from Brocade to AWS, from EMC to SAP.

Let’s see what can be proposed by the Brocade adapter, regarding the “Port” resources : (Request is : “GET /api/adapterkinds/BrocadeFabricAdapter/resourcekinds/Fabric/statkeys”).

20151126-vROps_REST_01-S008

I collapsed every field to avoid a screen capture of 35MB. I only kept 2 resources expanded, which are “Self Active Anomaly Count” and “Alert Count Critical”. You have tens of metrics using the Brocade adapter, only for the port. You can do the very same job for other resources of Brocade Switches (Fabric, Switch, whatever) and each will have its metrics associated.

7. To conclude

I hope this guide help you, my favourite reader, to understand how this API can be leveraged.

Using it, you can definitely build a full stack of XML files that are making lots of sense in your day to day job, identifying potential issues on your platform for each components.

Be sure to let a comment in case you need some informations. You can check references if you need.

8. Useful references and links

 

Share Button

Leave a Reply

Your email address will not be published. Required fields are marked *


*