Perl Interface to Tivoli Netcool Performance Flow Analyzer

Transcription

1 Perl Interface to Tivoli Netcool Performance Flow Analyzer April 2010 Perl Interface to Tivoli Netcool Performance Flow Analyzer Document version 1.1 PJ McKenna IBM Galway Laboratory Copyright International Business Machines Corporation 2010 US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

2 CONTENTS List of Tables... iii Revision History... iv 1 Introduction Description About this document Document conventions Introduction to auroradtools Typical TNPFA scripts Connect to TNPFA Log on Send command to TNPFA, interpreting the results Log off Disconnect A Scripting Example How to create Threshold Alerts for TNPFA Methods available to create threshold alerts using scripts Unified approach Split approach Unified Approach Example TNPFA and Threshold Alerts...5 ii

3 LIST OF TABLES Table 1: Table-style view of the configuration file... 6 iii

4 REVISION HISTORY Date Version Revised By Comments 15/03/ PJK Published as Documentation in the IBM Support Portal 21/04/ SD Document format revised iv

5 Introduction 1 Introduction Tivoli Netcool Performance Flow Analyzer offers (TNPFA) an application programming interface (API) to its backend. All configuration, control and database access functions are supported by the API. Advanced users can write custom scripts to export periodically into a desired output format. The scripting language can, furthermore, be used for event notification 1.1 Description This document outlines the TNPFA Perl interface and how it may be used to accomplish various tasks that lie outside the normal ambit of the tool. Section 3 describes a scripting example that allows the user to configure warning and critical threshold values for network traffic of any unit type for any aspect of a domain. 1.2 About this document This document is aimed at advanced TNPFA users who want to carry out tasks not supported by the graphical user interface Document conventions File system files or locations are in Courier New font, as are command line inputs, outputs and environmental variables. All variables in scripts are italicized. 1

6 Introduction to auroradtools 2 Introduction to auroradtools In order to facilitate external scripting access to the TNPFA API, the auroradtools Perl module has been created. The module allows a Perl script to perform a number of operations against the TNPFA server. In keeping with TNPFA API, each operation has a return status ($status) and return value ($ret). The return status is a number indicating whether or not the operation succeeded. A return status of 200 indicates success, any thing indicates a failure with the number indicating the nature of the problem. Normally the return value is the text that would be returned by TNPFA as a consequence of the operation you requested except for aurorad_connect() where the return value is the socket used to communicate with the TNPFA backend. Any Perl script using the auroradtools module to communicate with TNPFA must first connect to the TNPFA daemon then log in to a site before performing any other operations. Then the script interacts with the TNPFA system by sending it messages much like the way the web front-end sends to the TNPFA back end. To finish, the script must logout from the server and disconnect from the socket. Possible operations are: ($status, $ret) = aurorad_connect(); where $io = $ret if $status == 200 ($status, $ret) = aurorad_login($io, $site, $user, $pass); Logs in to the $site on TNPFA backend daemon using userid $user and password $pass. ($status, $ret) = aurorad_cmd($io, $query); Sends a command to TNPFA. The status of the command is stored in the first return value (here $status), the success or failure of the command is stored in the second return value ($ret). ($status, $ret) = aurorad_logout($io); Logs the user out of the site. ($status, $ret) = aurorad_disconnect($io); Disconnects the script from TNPFA. Lesser-used operations include ($status, $ret) = aurorad_get_sessionid($io) The current session ID is returned in the second return value ($ret). ($status, $ret) = aurorad_login_resume($io, $sessionid) A previous session may be resumed (if it is still present in TNPFA) by passing the previously extracted sessionid. aurorad_verbose($verbosity) 2

7 Introduction to auroradtools If the $verbosity parameter is 1 then it turns on a debugging aid that prints out the communication between script and TNPFA to the standard output. Set to 0 to turn off. 2.1 Typical TNPFA scripts The pseudocode for typical TNPFA scripts is as follows 1. Set up variables 2. Connect to TNPFA 3. Log on 4. Send commands to TNPFA, interpreting the results 5. Log off 6. Disconnect Connect to TNPFA Here is a snippet of code that connects to TNPFA: require("auroradtools"); # status and return values my ($s, $r); # the I/O handle my $io; ($s, $r) = aurorad_connect(); $io = $r; Note how the return value from aurorad_connect() is stored in the variable $io. This variable is the representation of the socket from the Perl script engine to TNPFA. Any commands sent to TNPFA will be sent using this same socket variable and received using it Log on After connecting, the script must log on to a site using the same user ID and password that the same use would use via the web front end: my $site = 'default'; my $user = 'joe'; my $pass = 'password123'; ($s, $r) = aurorad_login($io, $site, $user, $pass); 3

8 Introduction to auroradtools printf("ok\n"); Send command to TNPFA, interpreting the results The following snippet of code will query TNPFA to discover the currently logged in user s full name: Log off printf("retrieving full name... "); ($s, $r) = aurorad_cmd($io, "/ user get fullname"); printf("ok\n"); printf("fullname: %s\n", $r); Logging off can be achieved by using the following code fragment: Disconnect printf("logging out... "); ($s, $r) = aurorad_cmd($io, "/ session logout"); printf("ok\n"); Disconnecting can be performed as in this code fragment: printf("disconnecting... "); ($s, $r) = aurorad_disconnect($io); printf("ok\n"); 4

9 A Scripting Example How to create Threshold Alerts for TNPFA 3 A Scripting Example How to create Threshold Alerts for TNPFA Using scripting, it is possible to inspect the TNPFA database in more detail than the GUI supports. For example it is possible to use internal TNPFA functions to calculate the mean, sum, minimum or maximum for a particular time range. This is different from the running totals kept for each facet of each aspect. It should be noticed that the shortest time slice, or bucket, that TNPFA deals with, by default, is the 10-second window. If a 10MB flow over one second occurs then it is averaged into 1MB/s in that 10 second window. The maximum value in that 10 second slice is therefore 1MB/s. TNPFA contains an internal cron-like facility that allows TNPFA commands to be executed at a specified time and frequency. These commands include a facility to execute a script of TNPFA commands stored in a file or to run an external executable. In order to monitor the DB for threshold breaches it will be necessary to run scripts frequently enough that alerts are sent in a timely manner but not so frequently that the recipient of the alert is deluged in messages. 3.1 Methods available to create threshold alerts using scripts There are two approaches open for creating threshold alerts. The 'unified' approach and the 'split' approach which are both described below. The threshold alert example described in section 3.2 illustrates the unified approach Unified approach The 'unified' approach, as shown in the example in section 3.2, takes the form of an external program directly querying TNPFA and handling the data processing and alerting itself. The unified approach has the benefit of simplicity but has the drawback that user information such as account name and password must be recorded in the script or configuration file. This is an obvious security problem Split approach The 'split' approach splits the responsibility between a TNPFA script that produces the data and a second script that checks the data against threshold values and produces alerts. With the 'split' approach the script that extracts the data from TNPFA is executed by the internal TNPFA cron system so it does not need to store any user information. The major drawback is that this mechanism is much more complex and harder to configure and manage. 3.2 Unified Approach Example TNPFA and Threshold Alerts Here we present a mechanism that allows the user to configure warning and critical threshold values for the send and receive amounts of any unit for any aspect of a domain. A script will parse the configuration file and interrogate the TNPFA backend database to 5

10 A Scripting Example How to create Threshold Alerts for TNPFA discover the values corresponding to the criteria in the configuration file. If the values are not outside threshold values then they will still be recorded in the system log, but under an innocuous heading. First, here is the configuration file (adn.conf): total octets application octets Table 1: Table-style view of the configuration file Aspect Unit Lookback period (sec) Send Warn Level Send Critical Level Receive Warn Level Receive Critical Level total octets application octets The first line in the config file says that for the aspect total select the unit octets. Looking back seconds, warn if 40 billion or more octets were sent. If more than 50 billion were sent then mark this as critical. If 15 billion or more octets were received then warn about that. If 16 billion or more were received, say that is critical. This configuration file is read by the adn.pl Perl script. The script should be executed using the OS s cron facility or the TNPFA built-in cron. The pseudo-code for the script is as follows: 1. Use "auroradtools" TNPFA interface. 2. Set up variables for a known user account. 3. Connect to TNPFA. 4. Log in. 5. Select domain number "0" - the default domain. 6. Begin parsing configuration file. 7. For each line in the config file 8. Logout. a. Extract the aspect, unit, period, warn send, critical send, warn receive and critical receive values. b. Tell the back-end that we are interested in this aspect and unit. c. Ask the back-end for the total amount for sent and received for the last period (in seconds). d. Determine what to put in the log for the values detected. e. Add to the log 9. Disconnect. 6

11 A Scripting Example How to create Threshold Alerts for TNPFA The Perl code to achieve that is as follows: #!/usr/bin/perl -I. ### ### AURORAd Perl API Examples ### ### Description: AURORAd Perl API Examples ### ### $Author: mtc $ ### $Id: examples.pl :49:56Z mtc $ ### $Date: :49: (Wed, 16 Sep 2009) $ ### use strict; # include the aurorad-tool function set require("auroradtools"); # credentials my $site = 'default'; my $user = 'admin'; my $pass = 'tivoli'; # the I/O handle my $io; Use "auroradtools" TNPFA interface Set up variables for a known user account # status and return values my ($s, $r); # aurorad_verbose(1); ############ CONNECT TO THE BACKEND ($s, $r) = aurorad_connect(); $io = $r; Connect to TNPFA ############ LOG IN TO THE BACKEND ($s, $r) = aurorad_login($io, $site, $user, $pass); Log in 7

12 A Scripting Example How to create Threshold Alerts for TNPFA ############ SELECT DOMAIN 0 ($s, $r) = aurorad_cmd($io, "/ site domain select 0"); Select domain number "0" ########### GET DATA my $conf_file="./adn.conf"; open(dat, $conf_file) die("could not open adn.conf"); close(dat); my $aspect_conf; my $aspect; my $unit; my $recv_warn; my $recv_crit; my $send_warn; my $send_crit; my $seconds; my $send_msg; my $recv_msg; my $send; my $recv; Begin parsing configuration file For each line in the config file Extract the aspect, unit, period, warn send, critical send, warn receive and critical receive values. foreach $aspect_conf (@conf_data) chomp ($aspect_conf); ($aspect,$unit,$seconds,$send_warn,$send_crit,$recv_warn,$rec v_crit)=split(/\ /,$aspect_conf); #### GET THE NUMBER OF BYTES OF THE ASPECT TOTAL IN THE LAST 20 MINUTES printf("selecting aspect $aspect/$unit... "); ($s, $r) = aurorad_cmd($io, "/ site aspect select $aspect $unit"); printf("ok\n"); 8 Tell the backend that we are interested in this aspect and unit

13 A Scripting Example How to create Threshold Alerts for TNPFA my $end my $start my $query 00"; = time(); = $end - $seconds; = "/ site aspect get tva sum $start $end printf("getting values for the last $seconds seconds... "); ($s, $r) = aurorad_cmd($io, $query); printf("ok\n"); printf("query Result: $r"); ($send,$recv)=split(/\s/,$r); $send_msg="informational"; $recv_msg="informational"; if ($send >= $send_warn) $send_msg = "Warning threshold violation \($send_warn\)" if ($send >= $send_crit) $send_msg = "Critical threshold violation \($send_crit\)" if ($recv >= $recv_warn) $recv_msg = "Warning threshold violation \($recv_warn\)" if ($recv >= $recv_crit) $recv_msg = "Critical threshold violation \($recv_crit\)" ############ WRITE TO SYSTEM LOG Ask the back-end for the total amount for sent and received for the last period Determine what to put in the log for the values detected system("logger -t aurorad \"$aspect $unit TNPFA send $send $send_msg\""); system("logger -t aurorad \"$aspect $unit TNPFA receive $recv $recv_msg\""); Add to the log on using the aurorad tag for Omnibus. 9

14 A Scripting Example How to create Threshold Alerts for TNPFA ########### LOG OUT ($s, $r) = aurorad_cmd($io, "/ session logout"); ############ DISCONNECT FROM AURORAd ($s, $r) = aurorad_disconnect($io); Log out Disconnect exit(0); 10

15 A Scripting Example How to create Threshold Alerts for TNPFA Trademarks IBM and Tivoli are trademarks or registered trademarks of IBM Corporation in the United State and other countries Other company, product, and service names may be trademarks or service marks of others.

16 A Scripting Example How to create Threshold Alerts for TNPFA Copyright IBM Corporation 2010 IBM United States of America Produced in the United States of America All Rights Reserved The e-business logo, the eserver logo, IBM, the IBM logo, OS/390, zseries, SecureWay, S/390, Tivoli, DB2, Lotus and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries or both. Lotus, Lotus Discovery Server, Lotus QuickPlace, Lotus Notes, Domino, and Sametime are trademarks of Lotus Development Corporation and/or IBM Corporation. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries or both. Other company, product and service names may be trademarks or service marks of others. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. Information in this paper as to the availability of products (including portlets) was believed accurate as of the time of publication. IBM cannot guarantee that identified products (including portlets) will continue to be made available by their suppliers. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 4205 South Miami Boulevard Research Triangle Park, NC U.S.A.