NAME
    Karma - How to Monitor Multiple Oracle Databases

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.

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.

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.

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.

    `$ gunzip < DBI-1.03.tar.gz | tar xvf -'

    `$ cd DBI-1.03'

    `$ perl Makefile.PL'

    `$ make test'

    then as root:

    `$ 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.

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.

    -- `karma:*:AEON:karma:amrak'

    `redolog' `rollback' `tablespace' `slowsql' `hitratios'
    `fragmentation' `extents' `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:

    `$ 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'. Use `-h'
    for help.

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:

    `$ perl karmad -d 2 -c c:\mydir\karma.conf -k c:\mydir\doc_root'

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

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:

    o lynx browser support (no frames, no tables?)
    o configuration check tool (reads karma.conf file)
    o web interface
    o help page for adding new services
    o more services monitored
    - hitratios dictcache, rowcache
    - listener log monitor
    - trace/core file monitor
    - monitor sqlnet performance
    - archive dest directory
    - backup success
    - buffer busy waits
    - locks
    o karma.conf
    - specify frames/no frames/no tables support
    - specify no html pages generated, text only
    - vertical/horizontal arrangement option
    o whom to contact messages
    o look at adding graphing support with
        Cricket

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