NAME
Karma - Configuration Guide
DESCRIPTION
This guide will help you step through the process of editing the karma.conf configuration file to control the behavior of Karma.
Installing a read-only user in your database
Karma needs to login to your target databases in order to monitor them. If you're not doing alertlog or OS monitoring
click here,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:
SQL> @karma_user.sql
Enter value for karma_password: amrak
User created.
Grant succeeded.
Grant succeeded.
You can now use this user and the password you specified when configuring a karma.conf file.
click here for detailsBasic Editing of the karma.conf file
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.
The 'karma' line is a directive to karma of a database it needs to monitor.
karma:*:VENUS:karma:amrak karma:*:MARS:karma:amrak
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.
The format of most other lines in this file are:
SERVICE:X:Y:Z
The SERVICE can be one of these:
redologs rollback tablespaces slowsql alertlog hitratios fragmentation extents latch mts repqueue reperror
X - how often (in minutes) to monitor this info Y - warning threshold Z - alert threshold
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.
A very simple configuration would look like this:
redologs rollback tablespace slowsql hitratios fragmentation extents latch
In this case, the factory defaults for X, Y, and Z will be used. Conversely, set your own values:
tablespace:15:85:95
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.
Editing the karma.conf using Preference Groups
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:
karma:*:MARS:karma:amrak karma::MARS:karma:amrak karma:default:MARS:karma:amrak
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.
karma:New York:MARS:karma:amrak New York:tablespace:10:80:90 New York:slowsql New York:hitratios:2:85:95
Notice that the exact spelling is relevant here. Case is checked, as well as spaces. In fact, any characters between the colons matter.
For more information on configuring services, see the services documentation
here.
Email Notification
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:
notify_email:full:shull,root,oracle@somewhere.com,nobody@xyz.com
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.
Check the various *.conf files in the main directory.
Alertlog and OS monitoring
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.
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.
Install the tables in your karma schema first. Login as the karma user created above
(see user creation section)
and do the following:
SQL> @karma_objs
Creating karma_os_stats table...
Table created.
Creating karma_alertlog_errors table...
Table created.
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.
For more help with the karmagentd daemon, use the -h option:
$ ./karmagentd -h
h - print this help info f - fequency in minutes to wakeup & check things (default 1) r - reset the alert.log, and truncate it's table u - user to login as (default karma) p - oracle login password (otherwise you're prompted) j - jump j bytes in file (takes precedence over save file) t - tnsname of the database to watch (default local) a - specify alert.log file (default OFA) k - use this file to store seek position b - specify ORACLE_BASE (takes precedence over env) h - specify ORACLE_HOME (takes precedence over env) s - specify ORACLE_SID (takes precedence over env d - debug level (default 0, no debugging)
./karmagentd [ -h] [-f #] [-r] [-u karma] [-p pass] [-j #] [ [-t DB]<br-a alert.log] [-k karmagent.sav]> [-b ORACLE_BASE] [-h ORACLE_HOME] [-s ORACLE_SID] [-d #]
Using the karmactl utility
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.
To get help do $ perldoc karmactl or the following:
$ bin/karmactl -h
-h print help and exit -v print version and exit -w print warranty and exit -s start karmad daemon -p stop karmad daemon -t print status of running karmad daemon -r reload karam.conf config file -i specify process id (if lock file is missing) -l specify logfile for karmad (ignored if not starting karmad) -c specify karma config file (ignored if not starting karmad) -k specify karma doc_root -d delete dynamically created karma files (karma.html, info/*.html)
karmactl [-h|-v|-w|-s|-p|-t|-r|-d] [-l file] [-c file] [-k dir]
Get the status of a running karma daemon as follows:
$ bin/karmactl -s Starting karma daemon...
$ bin/karmactl -t 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