=head1 NAME

Karma - How to Monitor Multiple Oracle Databases

=for html <body bgcolor="#3399cc">

=head1 DESCRIPTION

An Oracle DBA has many responsibilities and day-to-day tasks to
complete. Karma was developed with the idea that many of these
tasks can be automated, thus freeing time for other useful work.
This presentation will discuss setup and configuration of Karma
to provide you with a simple web-interface for monitoring an
unlimited number of Oracle databases. 

=head1 Introduction

In the course of being an Oracle DBA, one is confronted with many 
varied tasks.  Some of them are mundane and repetitive, while
others require thinking, and debugging.  Karma was developed
with the idea of eliminating many of the day-to-day mundane and
repetitive tasks so a DBA can be left to spend time more wisely.

You'll find Karma is quite useful especially when you need to 
keep a watchful eye on many databases, as it can monitor 
a lot of important Oracle vital signs like latch contention,
hit ratios, tablespace quotas, max extents, redo log switching,
rollback segment contention, fragmentation, slow sql queries, 
alert log errors, and replication's deferred transaction, and
error queues.  In addition, Karma can be configured to send
email on warning or alert conditions, even notifying you by
alphanumeric pager if necessary.  In short, Karma can help you
be more proactive with respect to the databases you manage.


=head1 What it does and how

Karma is a web-based application, however, it has some very 
important differences from a normal CGI based application.
First a little bit of background.

With a CGI, generally, requesting a given url is actually a
request to apache to run a certain program.  In the case of
a database application, it would connect to the database, 
perform some function, disconnect, and return an HTML page
based on the results of the database requests.  This is
how dynamic web content is created on the web.  A lot of 
improvement over this has occured since it's beginnings,
like mod_perl, an apache module which caches your code, as
well as the database connections, making them persistent.  
All in all, these changes provided dramatic improvement over
earlier non-cached solutions, but still present some problems
for a database monitor.

In the case of Karma, this traditional scheme posed some
problems.  Besides the fact that CGI applications, if not 
written very cleanly, can pose some security risk, they
also constitute a hit each time they are called.  If many
users wanted to keep an eye on the databases monitored
each time they loaded the karma main page, they would be
hitting the database.  What's more there'd be no way to 
provide email notification in such a scheme.  There'd be
no program running until the user initiated in from the
browser.  

For these reasons I decided NOT to make this application
a simple CGI.  Instead, I built it as a unix daemon.  It 
is started once, and kept running in the background until
explicitely told to quit.  While running, it wakes up 
periodically, checks up on the database, generates the 
relevant HTML pages, and if necessary, sends out email
notification of any warning or alert conditions.  That's
it, it then happily goes back to sleep.

The HTML pages that are generated are static, so no matter
how often you load them in your browser, you DO NOT hit
the database at all.  It's like magic!  The real beauty is
in the refresh tag.  The main HTML page includes a 
tag which tells the browser to every so often reload the
page.  This is set to match the wakeup time of Karma, so
when a new page is generated, the browser will just
make a new request.


=head1 Installation

Honestly, it's not all bad.  First you'll need Oracle
installed of course.  Not for the database you'll be 
monitoring, but you'll need to install the client software
to get the Perl DBD-Oracle module to work.  In fact,
you'll need a bit more than just the client software
as DBD-Oracle is a compile C program, using the OCI
Oracle library to access the database.  Include the
Pro*C, and database itself when you install to be sure
you get everything DBD-Oracle needs to compile.  You can
delete much of it later.

To install a Perl module, you need only (1) uncompress
and untar, (2) generate the makefile, (3) make test, 
and finally (4) install.

C<$ gunzip < DBI-1.03.tar.gz | tar xvf ->

C<$ cd DBI-1.03>

C<$ perl Makefile.PL>

C<$ make test>

then as root:

C<$ make install>

You'll follow the same steps to install DBD-Oracle.  

After that, you'll be ready to do the same for Karma.
It's got a standard perl installer, with a Makefile.PL
so you can follow the same steps above to install.


=head1 Configuration and Setup

Get started quickly by editing the basic.conf file.  The
following gives a rough example.  The first line simply
specifies the database to connect to.  Use one for each
database you'd like to monitor.  The fields are:

<1>:<2>:<3>:<4>:<5>

1 - 'karma' a reserved word meaning this is a db spec line

2 - pref group, can be *, 'default', blank, or any string

3 - db, from your tnsnames.ora file

4 - username

5 - password

Below that you'll find the services you'd like to monitor.
These are reserved words, and although case is not important
they must be spelled correctly, or they'll be ignored.

--
C<karma:*:AEON:karma:amrak>

C<redolog>
C<rollback>
C<tablespace>
C<slowsql>
C<hitratios>
C<fragmentation>
C<extents>
C<latch>
--

Other features can be enabled such as non-blinking icons,
email notification, or preference groups (different
monitoring for each group).  See other *.conf files for 
details.

Finally you'll want to start the daemon:

C<$ karmactl -s -c myfile.conf>

If your config file is karma.conf, and is in the current
directory, then you don't have to specify it with C<-c>.
Use C<-h> for help.


=head1 Supported platforms 

Karma should run on any unix platform which Oracle provides
client libs and OCI for.  I've confirmed it's working on 
Linux, Sun Solaris, and DG-UX.  As far as NT and other Win32
platforms are concerned, it is working, but with some issues.
Essentially, the unix fork () system call is not supported
under Win32, as well as various signals.  These are all used
by karmactl, the assistant utility which can start and 
stop the daemon.  For that reason, for now karma only works
by calling the daemon directly on Win32 platforms. 
Something like this should work:

C<$ perl karmad -d 2 -c c:\mydir\karma.conf -k c:\mydir\doc_root>

Note that C<-d> option.  This turns debugging on, and cannot be
used from the karmactl utility.  You may find it useful.


=head1 Future Development

I have a LOT of great ideas for what I want to do with Karma,
but have not had time to get to them all.  2.0 will be coming,
that is, once 1.0 is out!  Here are some of the ideas I have so
far:

=over 4

=item
o lynx browser support (no frames, no tables?)

=item
o configuration check tool (reads karma.conf file)

=item
o web interface

=item
o help page for adding new services

=item
o more services monitored

=over 4

=item 
- hitratios dictcache, rowcache

=item
- listener log monitor

=item
- trace/core file monitor

=item
- monitor sqlnet performance

=item
- archive dest directory

=item
- backup success

=item
- buffer busy waits

=item
- locks

=back

=item
o karma.conf

=over 4

=item
- specify frames/no frames/no tables support

=item
- specify no html pages generated, text only

=item
- vertical/horizontal arrangement option

=back

=item
o whom to contact messages

=item
o look at adding graphing support with

=for html <a href="http://www.munitions.com/~jra/cricket/">

Cricket

=for html </a>


=item
o resetting services, once you've seen them, turn back to green
  (not sure if this fits into the non-CGI thinking so far...)

=item
o 7.x issues

=back




