Section 4.3. Karma

4.3 Karma

Sean Hull's Karma program takes Oracle database monitoring a step further. Like Oracletool, it is intended to help DBAs with their daily work. The program is especially helpful in automating the tracking of important, though tedious -to-collect information ” information that you may need to know, but be too busy to gather personally . Karma's comprehensive configuration capabilities let you select the particular features and database events to monitor, how often to monitor them, and how strictly to monitor them. (See Figure 4-8 for a sample screen produced by Karma.) You can also break up your many databases into groups, each with its own monitoring criteria and thresholds. Karma's goal is to help Oracle DBAs collect numerous useful statistics automatically in the background. Karma offers the ability to notify the DBA by email when database problems occur, and it provides a single place to keep track of many different databases.

Figure 4-8. The main Karma page indicating alarms

Because Karma collects a wider range of statistics than Oracletool's monitoring features do, and because it provides a full suite of online monitoring options, program installation and configuration are slightly more involved. Unlike Oracletool, Karma is not implemented as a CGI script. Instead, it runs a daemon, generating HTML pages in a specified location.

For complete information about Karma, go to:

http://hypno.iheavy.com/karma/

The following sections describe the installation on both Unix and Win32. In both environments, note that you may also need several other modules, depending on your requirements:

http://www.cpan.org/authors/id/M/MA/MARKOV/

Graham Barr's and Mark Overmeer's MailTools.pm Perl module. This is needed by Karma if you'll be using the email notification facility.

http://www.cpan.org/authors/id/KJALB/

The CPAN home of Kenneth Albanowski's TermReadKey.pm package; it's necessary for collecting operating system statistics under Unix.

http://www.cpan.org/authors/id/GBARR/

Graham Barr's home CPAN directory containing some of Perl's most influential modules, including the libnet library required by MailTools.pm .

4.3.1 Installing Karma on Unix

We downloaded the following file from the Karma site provided earlier:

karma-1.0.0.tar.gz

For Unix, follow these instructions:

1. Unpack your Karma tarball under a suitable Apache ../htdocs directory:

    $ cd /usr/local/apache/htdocs $ gzip -d karma-1.0.0.tar.gz $ tar xvf karma-1.0.0.tar $ cd karma-1.0.0 

2. There are a variety of installation document files; the QUICKSTART document is especially designed for those who want to just get on with it:

    $ vi README INSTALL  QUICKSTART  

3. When it's ready, Karma uses the Makefile.PL configuration method:

    $ perl Makefile.PL $ make 

4. Check that the make test step produces output such as the following, before installing:

    $ make test PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5. 6.1/i686-linux -I/usr/local/lib/perl5/5.6.1 test.pl ... ok 1 

   Now install:

    $ make install 

5. Before you run Karma, you may want to set the KARMA_HOME environment variable to ensure that the correct files are accessed by the daemon agents . You'll also need to set the Oracle environment:

     $ export KARMA_HOME=/usr/local/apache/htdocs/karma-1.0.0  $ export ORACLE_HOME=/u01/app/oracle/product/8.1.5 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib 

4.3.1.1 Installing TermReadKey.pm

If you will later want to check the alert log file for each database via Karma, you need to install the TermReadKey.pm module to keep passwords secret. It provides Perl with various input controls for reading console input and allowing specialized input, such as reading in passwords without echoing them back. Follow these steps:

1. Unpack the tarball from the CPAN web site provided earlier:

    $ gzip -d TermReadKey-2.14.tar.gz$ tar xvf TermReadKey-2.14.tar $ cd TermReadKey-2.14 

2. The command-line input effects are demonstrated by the make test step:

    $ perl Makefile.PL $ make $ make test ... This is ReadMode 2. It's just like #1, but echo is turned off. Great for passwords. You may enter some invisible text here:  You entered 'The Invisible Man'. 

3. If the tests work OK, go for the install:

    $ make install 

4.3.1.2 Installing MailTools.pm

If you're thinking of using Karma's automatic email options, you'll need to install MailTools.pm . To do this, you also need Graham Barr's libnet library. We're after two Perl modules contained within this bundle, Net::SMTP and Net::Domain . The full libnet module collection is summarized in Table 4-3.

Table 4-3. Modules available within Perl's libnet library

Perl libnet module	Description
Net::FTP	File Transfer Protocol
Net::SMTP	Simple Mail Transfer Protocol
Net::Time	Daytime Protocol
Net::NNTP	Network News Transfer Protocol
Net::POP3	Post Office Protocol 3
Net::SNPP	Simple Network Pager Protocol

You can get hold of the latest bundle, such as libnet-1.0704.tar.gz , from:

http://www.cpan.org/authors/id/GBARR/

Once you've unpacked the tarball, the perl Makefile.PL step does more configuration than most Perl module construction kits, and the test step also requires access to a list of Internet hosts . Be prepared to answer plenty of questions, especially during the installation stage. You can, however, skip these tests if you wish:

 $ perl Makefile.PL $ make  $ make test  $ make install 

We're now ready for MailTools.pm proper:

 $ gzip -d MailTools-1.40.tar.gz $ tar xvf MailTools-1.40.tar $ cd MailTools-1.40 $ perl Makefile.PL $ make $ make test $ make install 

4.3.1.3 Configuring Karma

To test Karma and create errors (which we're hoping the program will email us about), we created a ridiculously small TEMP temporary tablespace:

 CREATE TABLESPACE  TEMP  DATAFILE    '/u04/temp1orcl.ora' SIZE 10240 REUSE AUTOEXTEND OFF DEFAULT STORAGE (   INITIAL           4096   NEXT              2048   PCTINCREASE       0 ) TEMPORARY LOGGING ; 

Because we're intending to use OS monitoring, we now need our own special user located directly within the target database, with a SELECT ANY TABLE privilege. We also need a small set of statistical collection tables. We can accomplish this by running two scripts provided by Karma, in the ../sql directory:

karma_user.sql

karma_objs.sql

Running these two SQL scripts produces the following output, including the expected truncation error:

 SQL>  @karma_user  Enter value for karma_password:  seadevil  User created. Grant succeeded. Grant succeeded. SQL>  connect karma/seadevil  Connected. SQL>  @karma_objs  Creating karma_os_stats table... Table created. Creating karma_alertlog_errors table... Table created.  TRUNCATE TABLE karma_agent   *   ERROR at line 1  :  ORA-00942: table or view does not exist  Creating karma_agent table... Table created. 1 row created. SQL> 

Follow these steps:

1. As the nominated Oracle user, we can now get the Karma OS monitor agent going. The following script prompted us for the karma user password, seadevil , which then kicked off a daemonized karmagentd . This woke up every 300 configured seconds to check the alert log file specified:

    $ karmagentd -u karma -t ORCL -a  $ORACLE_HOME/rdbms/log/alert_orcl.log  

2. The statistics collected by karmagentd are then made accessible to the Web by the karmad program itself. We'll be kicking this off shortly as the root user. But first, we need to make sure that our configuration is right. We do this by altering the karma.conf file. The following example shows our karma.conf settings. These will check various database states and report back to us if warning or alert thresholds are crossed. Notice the notify_email tag, which tells Karma to whom to send emails. Additional help is available in the installation files.

    karma:Marlow:ORCL:karma:seadevil repqueue reperror Marlow:  notify_email:full:oracle   notify_alert:10:fragmentation,a,b,c   notify_warning:15:hitratios,a,b,c  Marlow:refresh:5:75 Marlow:redolog:1:30:15 Marlow:rollback:1:0:0 Marlow:tablespace:1:85:95 Marlow:slowsql:1:100:200 Marlow:alertlog:1:60:86400 Marlow:hitratios:1:95:70 Marlow:fragmentation:1:0:0 Marlow:extents:1:2:1 Marlow:latch:1:0:0 Marlow:mts:1:50:75 Marlow:os:1:5:10 warn_blink:true alert_blink:true pref_group_sections:true doc_root:/usr/local/apache/htdocs/karma-1.0.0/doc_root 

3. We can then start up the main karmad program:

    $ karmad -c $KARMA_HOME/karma.conf 

4. Two mail messages are now generated automatically by the Karma system and sent to the oracle OS user. These allow us to focus on the requisite errors via the web pages that show these warnings:

    Message 1: From root  Sun Sep  2 21:00:16 2001 Return-Path: <root> Received: (from root@localhost)         by localhost.localdomain (8.8.7/8.8.7) id VAA01389;         Sun, 2 Sep 2001 21:00:15 +0100 Date: Sun, 2 Sep 2001 21:00:15 +0100 From: root <[e-mail]> Message-Id: <[e-mail]> Subject: ORCL:ALRT:fragmentation,hitratios, To:  [e-mail]  Status: RO  ORCL database **ALERT** - The following services have problems  :  fragmentation   hitratios  & Message 2: From root  Sun Sep  2 21:00:16 2001 Return-Path: <root> Received: (from root@localhost)         by localhost.localdomain (8.8.7/8.8.7) id VAA01389;         Sun, 2 Sep 2001 21:00:15 +0100 Date: Sun, 2 Sep 2001 21:00:15 +0100 From: root <[e-mail]> Message-Id: <[e-mail]> Subject: ORCL:WARNING:alertlog, redolog To:  [e-mail]  Status: RO  ORCL database WARNING - The following services have problems  :  alertlog   redolog  & 

Checking on this later via the web browser, we'll also be able to find out something about our TEMP tablespace, with the information generated from our alert log file (see Figure 4-9).

Figure 4-9. Karma reporting on alert log errors

4.3.2 Installing Karma on Win32

At the time this book went to press, the full daemon karmagentd functionality of Karma had yet to be ported to a Win32 service. Even now, though, you can still do a lot with karmad :

1. Unzip the karma-1.0.0.tar.gz file into an unpack directory under Apache's ..\htdocs directory, such as:

   C:\Program Files\Apache Group \Apache\htdocs\karma-1.0.0

2. You then need to check out the following set of files:

   README

   README.WIN32

   INSTALL

   QUICKSTART

3. We'll assume here that you don't have the compilation facilities on your Win32 box that are required for an automatic installation of Karma. We'll therefore explain how to perform a manual installation.

4. We unpack the karmad program from its wrapper:

    $ cd bin $ perl karmad.PL 

   This should leave us with the Perl program, karmad .

   As with Unix, you may wish to create a Karma user within the target database. The ../sql/karma.sql script has been provided for this purpose. We're now ready to configure Karma for database action.

4.3.2.1 Configuring Karma on Win32

The karma.conf file itself contains plenty of help on how to configure Karma, though fortunately most of the configuration is fairly intuitive. The main configuration parameters we chose were:

  karma:Henley-On-Thames:ORCL:karma:dalek  repqueue reperror Henley-On-Thames:refresh:5:75 Henley-On-Thames:redolog:1:30:15 Henley-On-Thames:rollback:1:0:0 Henley-On-Thames:tablespace:1:85:95 Henley-On-Thames:slowsql:1:100:200 Henley-On-Thames:alertlog:1:60:86400 Henley-On-Thames:hitratios:1:95:70 Henley-On-Thames:fragmentation:1:0:0 Henley-On-Thames:extents:1:2:1 Henley-On-Thames:latch:1:0:0 Henley-On-Thames:mts:1:50:75 Henley-On-Thames:os:1:5:10 warn_blink:false alert_blink:false pref_group_sections:true  #doc_root: Commented out to use default Present Working Directory  

The database connection line at the top of the list is perhaps the most important thing to get right. We also decided to default the ..\doc_root to the present working directory.

4.3.2.2 Running Karma on Win32

To get the basic karmad program running, change to the main Karma home directory, make sure your target Oracle database is accessible via its listener, and then run the main Karma monitor program:

 C:\> cd C:\Program Files\Apache Group\Apache\htdocs\karma-1.0.0 C:\> perl bin\karmad -c karma.conf 

The daemonic karmad monitor periodically produces a series of HTML pages, which you can access via a web server (you can also access them directly with a local browser if you'd prefer). We liked the idea of the first option, so we started up Apache and then visited the following page:

http://localhost/karma-1.0.0/doc_root/index.html

You can see the first result in Figure 4-10.

Figure 4-10. The main Karma screen on Win32

4.3.2.3 Extra Perl modules for Win32

If you do want to push Karma to get mail notification and OS monitoring, you'll need to get hold of two more ActivePerl packages. Connect to the Internet and run ActivePerl's PPM program to install the MailTools package. You may also want to install TermReadKey in anticipation of the time that the daemon-based karmagentd will be ported to a service under Win32:

 C:\> ppm PPM> install MailTools PPM> install TermReadKey PPM> exit