[Nagios-db-checkins] nagios-db README,1.2,1.3

[Bench <be...@us...>]

Update of /cvsroot/nagios-db/nagios-db
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4271

Modified Files:
	README 
Log Message:
updated for new file release


Index: README
===================================================================
RCS file: /cvsroot/nagios-db/nagios-db/README,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- README	1 Feb 2005 06:18:39 -0000	1.2
+++ README	5 Feb 2005 00:33:54 -0000	1.3
@@ -1,66 +1,66 @@
 Nagios-DB is, not surprisingly, designed to add database support to
-nagios 2. I cared about database support because Nagios' flat file
+nagios 2. Database support is important because Nagios' flat file
 storage system doesn't make for acceptable UI performance as the
-environment becomes large. I also wanted to be able to do better
-historical reports than what nagios currently offers. That was my
-motiviation, and hence, that's what I've addressed.
+environment becomes large. Also, keeping data in a database allows
+for more complex historical reports to quickly and easily be 
+generated. These have been the prime motiviations to date, and 
+hence, these pain points are the ones that have been addressed.
 
-I've pretty much ignored every cool feature Nagios offers which do not
-apply to me. I made some effort to make sure they *could* be
-incorporated into this framework, but that's about it. I appreciate that
-those features are useful elsewhere, but not here where I work. 
+Pretty much every other cool feature Nagios offers has been ignored.
+Effort has been made to make sure those features *could* be
+incorporated into this framework, but that's about it. I appreciate 
+that those features are useful elsewhere, but there haven't been 
+important yet.
 
-It would be totally sweet if somebody came around and added support for
-the parts I ignored. I'll help when I can, but I'm a busy person.
+It would be totally sweet if somebody who cares about those ignored 
+nifty features came around and added support for them. (hint hint)
 
 Now, as for how it works.......
 
+
 OVERVIEW
 ========
 
 Nagios 2 adds a callback system called the Nagios Event Broker (NEB).
-You write a shared library that registeres for various callbacks while
-Nagios' processes data, and then (surprise!) your library gets called
-when nagios passes through those points. Because of the kind of data I
-care about, I only bothered to register for host and service status
+You write a shared library which registeres for various callbacks, and 
+then, while Nagios processes data, (surprise!) your library gets called
+when nagios passes through those points. Because of the kind of data
+Nagios-DB uses, it only bothers to register for host and service status
 callbacks, as well as a callback after the configuration has been parsed
 out. There are many other callbacks. Titus Anderson has written a
-quality example NEB module that shows what's there. I've placed it in
+quality example NEB module that shows what's available. I've placed it in
 neb/sampler/, and you can get it online at
 http://www.louisville.edu/~tjande01/nagios. Eventually we might even get
 Ethan to document this stuff. :)
 
 Anyway, NEB modules can do whatever you want them to - they're simply 
-shared libraries. The one I've included connects to a Postgres database 
-and calls some stored proceedures. That's it, as far as Nagios itself 
-is concerned.
+shared libraries. The one in neb/postgres/ connects to a Postgres database
+and calls some stored procedures. Likewise, neb/mysql/ houses a module 
+that does the same thing, but dumps its data into mysql. 
 
-Then we have the UI. In stock Nagios, the UI is a bunch of CGI programs
+That's it, as far as Nagios itself is concerned. Nagios-DB is entirely
+supplemental. Data still gets written to Nagios' native flat files, but
+with the UI included with Nagios-DB ignores it.
+
+Speaking of the UI... In stock Nagios, the UI is a bunch of CGI programs
 that read Nagios' flat files. With this system, the UI reads data from
-the database. I've hacked out a UI in PHP, but it is easily replaced
-and/or supplimented if somebody feels the itch. Anyway, this new UI
-architecture is better for a number of reasons. First, each web page
-load doesn't have parse Nagios' flat files on every run. For me, that is
-a HUGE win. Second, the web pages do not need access to Nagios' flat
-files at all. That means the filesystems on the webserver and Nagios
-don't have to be connected. Third, the interface don't have to be
-written in C (not that they had to be written in C before, but it sure
-made things easier).
+the database. A rough UI hacked out in PHP in included, but it is easily
+replaced and/or supplimented if somebody feels the itch. (In fact, Matthew
+Kent is currently working on a much improved, template-based PHP system.)
+Anyway, this new UI architecture is better for a number of reasons. First, 
+each  web page load doesn't have parse Nagios' flat files on every run. 
+With thousands of objects, that is a HUGE win. Second, the web pages do 
+not need access to Nagios' flat files at all. That means the filesystems 
+on the webserver and Nagios can be independant. Third, the interface 
+doesn't have to be written in C (not that they had to be written in C 
+before, but it sure made things easier).
 
 
 POSTGRES DATABASE DETAILS 
 =========================
 
-I wrote this to utilize postgres for my database. I needed the features
-and the standards compliance it offers. I have no plans to support any
-other database. That doesn't mean somebody can't use my NEB module and
-the following details as a guide in adding support for a different
-database. The UI shouldn't have to care what database is being used. 
-(Though features such as materialized views will help the UI
-be useable.)
-
-The way I wrote things, data is modified with stored proceedures. For
-instance, there is one proceedure for service status messages and
+In the postgres implementation, data is modified with stored proceedures. 
+For instance, there is one proceedure for service status messages and
 another for host status messages. The thinking here was that the logic
 for whether to insert a row or update a row isn't trivial, so putting it
 in a stored proceedure keeps the server from recomputing the same plan
@@ -72,23 +72,25 @@
 process, it has easy access to nagios' configuration after startup but
 before steady state. Currently, the NEB module reads config data such as
 hostgroups and monitoring features, and copies that information into the
-database. This is very handy when generating reports. Actually, because
-the UI only has access to the database, putting such information into
-the database is the only way to use it for reporting.
+database. This is very handy when generating reports. (Actually, because
+the UI only has access to the database, and not neccessarily Nagios'
+configuration files, putting such information into the database is the 
+only way to use it for reporting.)
 
 The table schema is simple. It is described in schema.sql. It is
 currently designed to host status information and hostgroup config, and
 not much else. It's easily expanded if more data becomes required.
 
-I've got about 5600 services in my environment. There are a lot of
-updates that happen with the database. It would be a very good idea to
-vacuum the database regularly.
+In large environments (and honestly, are you going to bother with this 
+unless you have a large environment?) there will be a lot of updates. 
+It would be a very good idea to vacuum the database regularly.
 
-A database may offer powerful information retrieval abilities, but for
-large environments, parsing through the entire database for every query
-is not going to offer much speed improvement over flat files. Therefore,
-the schema makes liberal use of materialized views. I am using
-materialized views as excellently described at
+Finaly, about the materialized views. A database may offer powerful 
+information retrieval abilities, but parsing through the entire database
+for every query is not going to offer much speed improvement over Nagios'
+default flat files. Therefore, the schema makes liberal use of 
+materialized views. I am using materialized views as excellently described 
+at
 http://jonathangardner.net/PostgreSQL/materialized_views/matviews.html.
 Currently, the views are snapshot views, and I recommend updating them
 as often as your hardware allows. You can either do so via running
@@ -99,12 +101,13 @@
 Let me explicitly restate this, because it's important: because the UI
 reads from snapshot materialized views, the data read will NOT be up to
 date. Depending on how often you refresh the views, it may or may not be
-close to realtime. While that is unfortunate to me, it is still
-acceptable (to me) to see data a minute or two old. On the other hand,
-it is NOT acceptable to wait 30 seconds to bring up a page. If you'd
-rather wait and make sure that you get the most recent data, even if it
-takes a long time to bring it together, you can always make the UI read
-from the non-materialized version of the view. 
+close to realtime. While that is unfortunate, it is still acceptable (to 
+me) to see data a minute or two old. On the other hand, it is NOT 
+acceptable to wait 30 seconds to bring up a page. If you'd rather wait 
+and make sure that you get the most recent data, even if it takes a long
+time to bring it together, you can always make the UI read from the 
+non-materialized version of the view. 
+
 
 MYSQL DATABASE DETAILS
 ======================
@@ -122,11 +125,13 @@
 The schema, like the postgres module, is simple but requires InnoDB 
 support.
 
-The gui itself now supports both databases, so it's just a matter
-of picking the right one in the configuration file. They *should* 
-function identically but differences may show up as more of the 
-interface is built out.
 
-See database/mysql/README
-    neb/mysql/inserter.c
-    ui/config.php
+UI DETAILS
+==========
+
+Thanks to a database abstraction layer in the UI, it doesn't matter 
+which database you choose to store your data in. Modifying 
+ui/config.php is all you need to do to switch between them. Indeed, 
+if you were insane, you could have Nagios load both NEB modules, save 
+data to both databases at the same time, and alter ui/config.php at 
+moment to pull data out of the either database.