Unisphere for VMAX has supported gathering of performance statistics with REST since Unisphere 1.6 back in 2013 so the functionality I am describing here is not new.  Lots of customers are already using REST with Unipshere to gather performance metrics for their own applications and working with this in their own applications.


All historical performance statistics stored in the performance database in Unisphere for VMAX can be extracted via REST calls at 5 minute granularity this means if you request an hour of data you will get 12 results for each 5 minute interval.  To be able to gather REST API statistics a read only account is required with the performance monitor privilege, this account will not be able to issue any REST API calls that would potentially make any changes on the array.  Also the array must be registered for performance stats collection on the Unisphere instance you are working with.

 

Gathering performance statistics our of Unisphere for VMAX for ingestion into 3rd Party applications is a quite common request doing so enables customers to correlate VMAX performance data with other applications data and environmental data from other sources, once such use case is getting the data into Splunk.   EMC have created a plugin that utilizes the Unipshere REST API to do just this.  If this is your primary use case for REST then you can explore this application on splunkbase app store it has no charge and will save you some work. You can find out more about this addon here https://github.com/ciarams87/PyU4V

 

Where can I locate the REST endpoints to Gather performance Stats?

 

The majority REST API performance calls are located under the endpoint /restapi/performance/ additional performance metrics can be located under the version which released the new metric e.g. /univmax/restapi/81/performance/Host.  It's worth noting in version 8.4 due in may 2017 all endpoints will  be brought forward under the /univmax/restapi/84/ endpoints so all features and metrics are accessible under a common REST endpoint, existing scripts will continue to work with the legacy calls however should be migrated to the new endpoints and validated.

 

REST calls can be made to Unisphere to get performance statistics using the various URI EndPoints under the performance section of the REST API.  By now you should be familiar with building your JSON payloads, in this post we will look at how we can use the REST API to gather multiple metrics using a single call to make more efficient calls to the REST Server.

 

Gathering performance statistics from Unisphere for VMAX REST API is always a POST (Create) call.  This may seem counter intuitive but the REST call will construct a return object based on the JSON payload parameters and the server the server will respond with this object as a JSON object containing the requested data.

 

REST calls for performance data require that date/times are specified in epoch/Unix time (the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, [note 1] not counting leap seconds).   All Timestamps are in milliseconds so you will need to take this into account when building the payload start_date and end_date.

 

Notes for building JSON Payloads to collect multiple metrics

 

A JSON Payload can be constructed to request multiple metrics with a single call. This can be more efficient as there is no need to make multiple requests, and the amount of code required to gather the requested data is thus reduced. Each metric we want to collect is requested as a  "value" is requested using the metrics key within the square brackets when specifying multiple values each is encased in double quotes and comma separated.  Below is an example payload, all these values are returned with a single call.

multimetrics.png

 

 

Collecting Stats for multiple components.

 

Unless you are querying for performance statistics at an array level it is more than likely there are multiple components under a performance resource where stats are being collected, As per the example above we will always have more than one front-end director,  similarly we will always have multiple storage groups etc.  If you want to collect performance stats for multiple ports then you will need to make multiple REST calls to the same endpoint for each unique component for example director FA-1D and FA-2D.

 

To make things easier for cusotmers, rather than making multiple Get calls and filter by type etc which would require more than a few lines of code and probably extensive use of regular expressions, you can simply use the keys for each of the performance endpoints and get a list of the components.  For example if I wanted to get a list of the front end directors for a particular array to gather metrics for each I can make a single call to the /performance/FEDirector/keys endpoint and pass the serial number for the VMAX array this will return a list which can be parsed to extract the directorID which can be used in additional calls.

perfkeys.png

 

As with Previous posts we will look at some sample scripts for gathering performance statistics.  The examples here are shown in python however payloads should be exactly the same regardless of the programming language you choose to implement.

Source Code can be found on Github GitHub - ciarams87/PyU4V: A library showing some of the functionality possible using the ReST API of UniSphere for VMAX

 

The example here is Get_FE_Stats_LastHour.py Click on the image to get a better view

get_perf_1hr.png

 

I've purposely left the main function get_last_hour_fe_metrics in the main script call as I want to illustrate how the returned payload is being manipulated in this script.  First off the script is getting a list of front end directors using the REST call to generate the keys. A simple loop is used to go through each front end director in the list and generate the performance data.  Since we are gathering data for multiple components using the same rest call with different director ID the returned JSON doesn't actually contain the director id. So if we are looping through multiple components we may not know which result list is associated with which director when we go to look at this information later.  Fear not!!  The example above has some neat tricks in it to modify the payload returned.

 

returnedperfJSON.png


The example strips out the highlighted pieces in the payload and wraps them in a new dictionary object with some additional key values to ensure the data is easier to parse.  We use similar methodology in the splunk add-on. 

 

The returned JSON as a result is easier to process, a subset of the result is shown before for a single 5 minute period.    I used online json formatter to make this pretty https://jsonformatter.curiousconcept.com/

blogjsonpretty.png


Using the methodology above I can easily repeat this for other performance calls I want to make and customize the returned payloads so other applications parsing the data will have an easier time. 

 

The example I have provided here Get_FE_Stats_LastHour.py has already been posted to github, and there are a number of additional example functions included in the rest_univmax on github https://github.com/ciarams87/PyU4V/

 

Summary.

 

In this post we looked at how to get performance data for you VMAX using the REST API, the example script looks at how to generate keys for the performance resources and build lists lists which can be iterated in order to gather and combine the returned performance data into structured JSON payloads that can be consumed by third party apps using the appended keys.  more examples are provided on the GitHub.   As always we would encourage customers to expand and build on the examples we have provided and contribute some of your own in the spirit of sharing is caring we really do want to encourage a good DevOps community where people can contribute and share.

 

The examples here are all provided in python and have been tested in Python 3.4,  while python may not be everyones language of choice the principles discussed here are equally applicable to any language.  Feel free to share your own examples by creating a Pull to our GitHub

or you can post a link here in the comments.

 

Just a note, REST is very useful for gathering all of these performance metrics but it is not a tool for actual troubleshooting,  if you are looking to root cause storage problems then you are best to use the existing tools such as Unisphere for VMAX's own performance GUI or utilize a third party application that will help you graph and correlate information.