<HTML>
<HEAD>
<TITLE>Karma - Configuration Guide</TITLE>
<LINK REV="made" HREF="mailto:root@porky.devel.redhat.com">
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#NAME">NAME</A>
<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
<LI><A HREF="#Installing_a_read_only_user_in_y">Installing a read-only user in your database</A>
<LI><A HREF="#Basic_Editing_of_the_karma_conf_">Basic Editing of the karma.conf file</A>
<LI><A HREF="#Editing_the_karma_conf_using_Pre">Editing the karma.conf using Preference Groups</A>
<LI><A HREF="#Email_Notification">Email Notification</A>
<LI><A HREF="#Alertlog_and_OS_monitoring">Alertlog and OS monitoring</A>
<LI><A HREF="#Using_the_karmactl_utility">Using the karmactl utility</A>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="NAME">NAME</A></H1>
<P>
Karma - Configuration Guide
<body bgcolor="#3399cc">
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
This guide will help you step through the process of editing the karma.conf
configuration file to control the behavior of Karma.
<P>
<HR>
<H1><A NAME="Installing_a_read_only_user_in_y">Installing a read-only user in your database</A></H1>
<P>
Karma needs to login to your target databases in order to monitor them. If
you're not doing alertlog or OS monitoring
<A HREF="config.html#agent">click here,</A>
<P>
then Karma is completely read-only. If you're concerned about Karma making
changes in your database, create a read-only user for it to login as. The
supplied script $KARMA/sql/karma_user.sql will do just that. Examine the
script, then login as sys, and run it like this (we're assuming here that
you've cd'd into the ``sql'' directory:
<P>
SQL> @karma_user.sql
<P>
Enter value for karma_password: amrak
<P>
User created.
<P>
Grant succeeded.
<P>
Grant succeeded.
<P>
You can now use this user and the password you specified when configuring a
karma.conf file.
<A HREF="config.html#conf">click here for details</A>
<P>
<HR>
<H1><A NAME="Basic_Editing_of_the_karma_conf_">Basic Editing of the karma.conf file</A></H1>
<P>
The karma.conf file is the core configuration file for karma. Eventually it
will be updatable via a web front-end, but for now one must edit the file.
<P>
The 'karma' line is a directive to karma of a database it needs to monitor.
<P>
<CODE>karma:*:VENUS:karma:amrak</CODE>
<CODE>karma:*:MARS:karma:amrak</CODE>
<P>
In this case karma will monitor the VENUS and MARS databases. The last two
parameters are the username and password to login with. 'MARS' and 'VENUS'
must be defined in the tnsnames.ora file otherwise an error will be
returned.
<P>
The format of most other lines in this file are:
<P>
<CODE>SERVICE:X:Y:Z</CODE>
<P>
The SERVICE can be one of these:
<P>
redologs rollback tablespaces slowsql alertlog hitratios fragmentation
extents latch mts repqueue reperror
<P>
X - how often (in minutes) to monitor this info Y - warning threshold Z -
alert threshold
<P>
A service is not monitored if it's time column is 0, or it is commented out
with the # character, or if it is not in the file at all. For repeated
entries, the last one listed will be used.
<P>
A very simple configuration would look like this:
<P>
<CODE>redologs</CODE>
<CODE>rollback</CODE>
<CODE>tablespace</CODE>
<CODE>slowsql</CODE>
<CODE>hitratios</CODE>
<CODE>fragmentation</CODE>
<CODE>extents</CODE>
<CODE>latch</CODE>
<P>
In this case, the factory defaults for X, Y, and Z will be used.
Conversely, set your own values:
<P>
<CODE>tablespace:15:85:95</CODE>
<P>
Which directs karma to check up on tablespace quotas every 15 minutes,
flagging a warning if they are 85% full, or an alert if they are 95% full.
<P>
<HR>
<H1><A NAME="Editing_the_karma_conf_using_Pre">Editing the karma.conf using Preference Groups</A></H1>
<P>
By default karma uses a default preference group. That's what the '*' is
for in the second field. It can also be blank, or the word default:
<P>
<CODE>karma:*:MARS:karma:amrak</CODE>
<CODE>karma::MARS:karma:amrak</CODE>
<CODE>karma:default:MARS:karma:amrak</CODE>
<P>
All three achieve the same result. However, one can break the preference
settings up into groups. These are given case sensitive names in this karma
line, and karma then looks for config lines later in the file, PREPENDED
with this name.
<P>
<CODE>karma:New York:MARS:karma:amrak</CODE>
<CODE>New York:tablespace:10:80:90</CODE>
<CODE>New York:slowsql</CODE>
<CODE>New York:hitratios:2:85:95</CODE>
<P>
Notice that the exact spelling is relevant here. Case is checked, as well
as spaces. In fact, any characters between the colons matter.
<P>
For more information on configuring services, see the services
documentation
<A HREF=services.html>here</A>
<P>
.
<P>
<HR>
<H1><A NAME="Email_Notification">Email Notification</A></H1>
<P>
Email notification is an important part of any monitoring app, so I've
tried to get this functionality working well in 1.0. At it's most basic
form, you add a line in your config file like this:
<P>
<CODE>notify_email:full:shull,root,oracle@somewhere.com,nobody@xyz.com</CODE>
<P>
The first field is obviously the directive. The second can be 'full' or
'short'. The 'short' format email is a very limited message suitable for
text pagers which often have an 80 character limitation. The third field is
a comma delimited list of email addresses.
<P>
Check the various *.conf files in the main directory.
<P>
<HR>
<H1><A NAME="Alertlog_and_OS_monitoring">Alertlog and OS monitoring</A></H1>
<P>
Karma has the ability to monitor the alertlog file and some OS statistics
of some or all of your target databases. This is a some what labor
intensive task that the dba must perform regularly and my goal here is to
simplify this task.
<P>
If you're going to monitor the alertlog you must create the
KARMA_ALERTLOG_ERRORS table, and if you are going to monitor OS stats, you
must create the KARMA_OS_STATS table. For monitoring either, you must
startup the karmagentd daemon.
<P>
Install the tables in your karma schema first. Login as the karma user
created above
<a href=config.html#user">
<P>
(see user creation section)
</a>
<P>
and do the following:
<P>
SQL> <CODE>@karma_objs</CODE>
<P>
Creating karma_os_stats table...
<P>
Table created.
<P>
Creating karma_alertlog_errors table...
<P>
Table created.
<P>
Monitoring is achieved via the karmagentd daemon. This daemon must be run
on *each* target database. This is necessary because the alertlog is an OS
logfile, which is only accessable locally on the machine. Karmagentd reads
the alertlog and keeps track of it's file position, periodically waking up
to check for changes. In addition, it will run ``uptime'' on that machine
as well. When it finds any ORA-xxx errors in the alert log, it writes them
to KARMA_ALERTLOG_ERRORS, and KARMA_OS_STATS respectively.
<P>
For more help with the karmagentd daemon, use the <CODE>-h</CODE> option:
<P>
<CODE>$ ./karmagentd <CODE>-h</CODE></CODE>
<P>
<CODE>h - print this help info</CODE>
<CODE>f - fequency in minutes to wakeup & check things (default 1)</CODE>
<CODE>r - reset the alert.log, and truncate it's table</CODE>
<CODE>u - user to login as (default karma)</CODE>
<CODE>p - oracle login password (otherwise you're prompted)</CODE>
<CODE>j - jump j bytes in file (takes precedence over save file)</CODE>
<CODE>t - tnsname of the database to watch (default local)</CODE>
<CODE>a - specify alert.log file (default OFA)</CODE>
<CODE>k - use this file to store seek position</CODE>
<CODE>b - specify ORACLE_BASE (takes precedence over env)</CODE>
<CODE>h - specify ORACLE_HOME (takes precedence over env)</CODE>
<CODE>s - specify ORACLE_SID (takes precedence over env</CODE>
<CODE>d - debug level (default 0, no debugging)</CODE>
<P>
<CODE>./karmagentd [<CODE>-h</CODE>] [-f #] [-r] [-u karma] [-p pass] [-j #]</CODE>
<CODE><PRE> [C&lt;-t&gt; DB]&lt;br
</PRE>
</CODE> [<CODE>-a</CODE> alert.log] [<CODE>-k</CODE> karmagent.sav]>
<CODE><PRE> [C&lt;-b&gt; ORACLE_BASE] [C&lt;-h&gt; ORACLE_HOME] [C&lt;-s&gt; ORACLE_SID] [-d #]
</PRE>
</CODE>
<P>
<HR>
<H1><A NAME="Using_the_karmactl_utility">Using the karmactl utility</A></H1>
<P>
The karmactl utility is a new addition to karma, and enables you to more
easily manage a running karma daemon. You can use it to stop or start the
daemon, get status on a running daemon, reread the config file or force a
refresh of all services.
<P>
To get help do <CODE>$ perldoc karmactl</CODE> or the following:
<P>
<CODE>$ bin/karmactl <CODE>-h</CODE></CODE>
<P>
<CODE>-h print help and exit</CODE>
<CODE>-v print version and exit</CODE>
<CODE>-w print warranty and exit</CODE>
<CODE>-s start karmad daemon</CODE>
<CODE>-p stop karmad daemon</CODE>
<CODE>-t print status of running karmad daemon</CODE>
<CODE>-r reload karam.conf config file</CODE>
<CODE>-i specify process id (if lock file is missing)</CODE>
<CODE>-l specify logfile for karmad (ignored if not starting karmad)</CODE>
<CODE>-c specify karma config file (ignored if not starting karmad)</CODE>
<CODE>-k specify karma doc_root</CODE>
<CODE>-d delete dynamically created karma files (karma.html, info/*.html)</CODE>
<P>
<CODE>karmactl [<CODE>-h</CODE>|<CODE>-v</CODE>|-w|-s|-p|-t|-r|-d] [-l file] [-c file] [-k dir]</CODE>
<P>
Get the status of a running karma daemon as follows:
<P>
<CODE>$ bin/karmactl -s</CODE>
Starting karma daemon...
<P>
<CODE>$ bin/karmactl -t</CODE>
karmad started at 19:46 pid:2853 Using EMAIL for notification DB:AEON UP,
Prefgroup:default - services: 19:46 -- os 19:46 -- mts 19:46 OK tablespace
19:46 OK slowsql 19:46 OK up 19:46 WARN hitratios 19:46 OK rollback 19:46
-- alertlog 19:46 OK extents 19:46 OK latch 19:46 OK redolog 19:46 OK
fragmentation
</BODY>
</HTML>