Vinod Subramaniam

Roll out your own monitoring dashboard with the HCS REST API

Blog Post created by Vinod Subramaniam on Jun 9, 2014

Introduction

 

The release of HCS 8.0.0-00 comes with support for the REST API. At its most basic level the REST API lets you interact with the RAID Agent store via http or https and retrieve performance metrics from a remote app within a firewall without port forwarding in place or even outside a firewall if port forwarding is implemented.

 

This opens up a world of possibilities for Third Party Developers, In house apps that require performance metrics, mobile platforms etc. You could for e.g. write a iOS app that retrieves performance information periodically and produces summary reports for the day or a Visual Basic or C# app that retrieves performance metrics in real time and highlights the metrics that cross a threshold in red and you could display affected applications on a large display at your DC operations center and so on.

 

This article illustrates the power of the rest API through a UNIX top like perl script that display VSP Ports, LDEVs, Pools and MPs in a sorted fashion with the most busy component displayed on top. You can also change the sort column for e.g from Read Transfer to Write Transfer for LDEVs etc.

 

Here is a short video of the command line dashboard running on RHEL 6.4 and monitoring a VSP

http://storageinfo.us/wp-content/uploads/2014/06/2014-06-09_1742.swf

 

The below set of screens show the various screens in the default sort order.

The screen will update metrics every 60 secs since that is the collection interval for the RAID Agent.

It requires that you change collection interval for PI_PLS, PI_LDA and PI_LDS to 60 secs. The default is 300 secs.

 

Figure 1 :- Port Information sorted by MAX_IOPS. You can change the sort column using the key "2".

This is the default startup screen. You can switch to this screen using the key "P".

Port.PNG

 

Figure 2:- LDEV Information sorted by Read IOPS

To view this screen use the key "L"

 

 

Figure 3:- Pool Information sorted by Read IOPS

To view this screen use the key "D".

 

 

Figure 4:- Microprocessor Information sorted by Busy%

To view this screen use the key "M"

 

 

Running the code

 

Tested on SLES 11 SP1 and RHEL 6.4 with Perl 5.10.

 

Perl Libraries required

 

9 # DECLARE IMPORTS

10

11 use Curses::UI::POE;

12 use List::Util qw(max);

13 use MIME::Base64;

14 use REST::Client;

 

 

Line 11 in vsptop.pl imports the Curses::UI::POE library.

To install run the command below after ensuring internet connectivity

 

Line 14 imports the REST::Client library. Install using cpan -fi REST::Client

 

[root@RHEL64-2 pub]# cpan -fi Curses::UI::POE

CPAN: Storable loaded ok (v2.20)

Going to read '/root/.cpan/Metadata'

  Database was generated on Mon, 09 Jun 2014 10:06:21 GMT

Running install for module 'Curses::UI::POE'

CPAN: Data::Dumper loaded ok (v2.124)

'YAML' not installed, falling back to Data::Dumper and Storable to read prefs '/root/.cpan/prefs'

Running make for T/TA/TAG/Curses-UI-POE-0.04.tar.gz

CPAN: Digest::SHA loaded ok (v5.47)

CPAN: Compress::Zlib loaded ok (v2.02)

Checksum for /root/.cpan/sources/authors/id/T/TA/TAG/Curses-UI-POE-0.04.tar.gz ok

CPAN: Archive::Tar loaded ok (v1.58)

.....

Running make install

Prepending /root/.cpan/build/Curses-UI-POE-0.04-KY1FJw/blib/arch /root/.cpan/build/Curses-UI-POE-0.04-KY1FJw/blib/lib to PERL5LIB for 'install'

Appending installation info to /usr/lib64/perl5/perllocal.pod

  TAG/Curses-UI-POE-0.04.tar.gz

  make install  -- OK

 

 

Putty settings for Pretty Printing

 

Change the font to "Consolas" with the script set to "Central European". This will allow the Perl script to use the upper ASCII box drawing characters.

 

putty1.PNG

 

Change the translation to ISO-8859-15:1999.

 

putty2.PNG

 

Change global constants in the script

 

     62 # DECLARE CONSTANTS FOR TUNING MANAGER

     63

     64 my $api_key = "system";

     65 my $api_pass = "XXXXXX";

     66 my $AGENT = "VSP_53086";

     67 my $HOSTNAME = "RHEL64-2";

     68 my $IPADDR = "172.17.237.129";

     69 my $HTTPS_URL = 1;

     70 my $HTTP_PORT = 22015;

     71 my $HTTPS_PORT = 22016;

 

Line 64 : This is the read only Tuning Manager user id.

Line 65 : This is the password for the user id from Line 64

Line 66 : This is the agent instance name that was provided when the RAID agent was setup

Line 67 : The hostname that runs the REST API component

Line 68 : IP Address associated with the hostname from Line 67

Line 69 : Set to 1 if you are using 22016 otherwise set to 0

 

 

Running the script

Unzip and untar the attachment vsptop-v1.1.tar.gz to a directory e.g /usr/local/hitachi

 

Edit the wrapper script vsptop.sh. This is the script that runs vsptop.pl

In this example change line 08 to /usr/local/hitachi/pub/vsptop.pl 2> /tmp/error.code.log

 

#!/bin/bash
CURRENT_LANG=$LANG
CURRENT_TERM=$TERM
export TERM=xterm-256color
export LANG=es_US.utf8
export PERL_LWP_SSL_VERIFY_HOSTNAME=0
# Do not redirect STDOUT owing to Curses issues
/root/REST/pub/vsptop.pl 2> /tmp/error.code.log
if [ $? -ne 0 ]
then
        echo "Non Zero return code detected";
        echo "Check /tmp/error.code.log         ";
        echo "Email the above file to vinod.subramaniam@hds.com";
fi
export TERM=$CURRENT_TERM
export LANG=$CURRENT_LANG










 

 

Summary of keys to switch screens

 

q --> quit

P -> Port Screen

M -> Microprocessor Screen

L -> LDEV Screen

D -> Pool Screen

 

Quick Code Walkthrough

 

21 my $REFRESH_RATE = 1;

22 my @lines = [];

214 $CUI->mainloop;

 

Line 21 declares the granularity of the timer for the main loop for the curses UI object on Line 214.

 

Line 22 declares the array that will populate the curses listbox object

 

       78 my $CUI =

     79         Curses::UI::POE->new(

     80         -color_support => 1,

     81         inline_states => {

     82                 _start => sub {

     83                         $poe_kernel->delay(

     84                                 'wake_up',

     85                                 $REFRESH_RATE

     86                         );

     87                 },

     88                 wake_up =>

     89                         \&wake_up_handler,

     90                 chld => sub {

     91                         waitpid $_[ARG1], 0;

     92                 },

     93         }

     94 );

     95

     96

     97 my $WIN =

     98         $CUI->add(

     99                 qw( win_id Window ));

    100

    101 my $TOP = $WIN->add(

    102                 qw( top Label

    103                 -y 0 -width -1

    104                 -paddingspaces 1

    105                 -fg white -bg blue

    106                 ), -text => "Hitachi VSP Top Resource Usage Display -->"

    107 );

    108

    109

    110 my $METRIC_HEADER = $WIN->add(

    111                         qw( header Label

    112                         -y 4 -width -1

    113                         -paddingspaces 1

    114                         -fg blue -bg white

    115                         ), -text => ""

    116 );

    117

    118 my $CACHE_SUMMARY = $WIN->add(

    119                         qw( cache Label

    120                         -y 1 -width -1

    121                         -paddingspaces 1

    122                         -fg black -bg white

    123                         ), -text => "Cache Summary | "

    124 );

    125

    126 my $STORAGE_SUMMARY = $WIN->add(

    127                         qw( storage Label

    128                         -y 2 -width -1

    129                         -paddingspaces 1

    130                         -fg black -bg white

    131                         ), -text => "Storage Summary | "

    132 );

 

Lines 98 through 132 declare the Curses UI objects , A window called $WIN, a labels called $TOP, $METRIC_HEADER, $CACHE_SUMMARY and $STORAGE_SUMMARY.

 

         142 my $LBOX = $WIN->add(

    143         qw( lb Listbox

    144                 -y 4

    145                 -padtop 1 -padbottom 1

    146                 -fg green -bg black

    147                 -border 1

    148                 ), -onchange => \&list_changed

    149 );

    150

    151

    152 my $BOTTOM = $WIN->add(

    153                 qw( bottom Label

    154                 -y -1 -width -1

    155                 -paddingspaces 1

    156                 -fg white -bg blue

    157                 ), -text => "VSP Watcher v1.0"

    158 );

 

Lines 142 through 158 is more Curses UI Objects a Listbox called $LBOX and a label called $BOTTOM.

 

Metrics are gathered via the rest API every minute and the array @lines is populated with metric lines.

The array @lines is then sorted and the listbox @LBOX is populated. Every time a sort key 1-9 is pressed this array is resorted and the listbox updated

 

The heart of the code : The REST API calls

 

         470                 my $client = REST::Client->new();

    471

    472                 my $RECORD_PORT = "RAID_PI_PTS";

    473                 my $FIELDS_STR_PORT = "PORT_NAME%1FMAX_IO_RATE%1FMAX_XFER_RATE%1F";

    474

    475

    476                 #Set the HTNM URL and encode the userid and password using BASE64 encoding

    477                 $client->setHost(get_htnm_url());

    478                 $client->addHeader("Authorization", "Basic " .

    479                     encode_base64("$api_key:$api_pass", ""));

    480

    481                 # Define the REST HTTP GET URL with the metrics that you desire. The metric names are in the User Guide.

    482

    483                 my $url_port = "/v1/objects/" . $RECORD_PORT . "?agentInstanceName=" . $AGENT . "&hostName=" . $HOSTNAME . "&startTime=" . $static_start . "&endTime=" . $static_end . "&fields=" . $FIELDS_STR_PORT;

    484                 my $response_port = $client->GET($url_port);

    485                 $BOTTOM->text(  get_local_time() . " : Watching VSP " . $AGENT . " on HTNM REST Host " . $HOSTNAME . " | Fetching => " . get_htnm_url() . $url_port ); $BOTTOM->draw();

    486

    487                 # Check the HTTP response code.

    488

    489                 my $HTTP_RESPONSE = $client->responseCode();

    490

    491                 if ( $HTTP_RESPONSE != 200 ) {

    492                     open(my $errors, ">>" , "/tmp/error.code.log");

    493                     print $errors $client->responseContent();

    494                     close $errors;

    495                     exit $HTTP_RESPONSE;

    496                 } else {

    497                         my $response = $client->responseContent();

 

 

Line 470 declares a REST Client object.

Line 472 stores the performance record type in a variable i.e RAID_PI_PTS is the port performance record

Line 473 selects the performance metric fields to display

A complete description of the records can be found in the API Guide http://www.hds.com/assets/pdf/hitachi-tuning-manager-api-reference-guide.pdf

and in the Tuning Manager manuals --> http://www.hds.com/assets/pdf/hitachi-tuning-manager-software-hardware-reports-reference.pdf

 

Lines 477 through 479 ensure that there is a login prior to a HTTP get.

Line 483 builds the URL for the HTTP get.

Line 484 is the actual HTTP get.

Line 491 checks the HTTP RESPONSE.

Anything other than 200 results in an exit with the HTTP RESPONSE CODE.

 

 

Summary

This short article shows the power of the REST API to aid in performance data visualization. Instead of a command line Curses app aka UNIX top like app you could build a full scale dashboard with graphs using VB or C#. In the next installment of this article I will do just that --> a realtime performance monitoring application in Visual Basic using the REST API. In addition I will show you how to build the below correlations into the application

PORT->HOSTGROUP->LDEV

HOSTGROUP-PORT-LDEV

LDEV->PORT-HOSTGROUP

LDEV-HOSTGROUP-PORT

and so on.

Attachments

Outcomes