SBLIM Performance Data Gatherer and Provider
============================================

(C) Copyright IBM Corp. 2003, 2004

 THIS FILE IS PROVIDED UNDER THE TERMS OF THE COMMON PUBLIC LICENSE
 ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
 CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.

 You can obtain a current copy of the Common Public License from
 http://oss.software.ibm.com/developerworks/opensource/license-cpl.html

Author: Viktor Mihajlovski <mihajlov@de.ibm.com>
Last Change Date: 10/20/2004

Changelog:
10/17/2003	Initial Version.
02/20/2004	Added test cases for SBLIM testsuite.
07/16/2004	Started prototyping for version 2
10/20/2004	Many changes: remote repository (by Heidi Neumann),
		logging, tracing and config file processing.
		Association Providers for Metric Values completed.


**** IMPORTANT NOTE ****
This version of the package is a very early prototype. Do not use!
Download a supported version from the SBLIM website instead.
You will find it at http://oss.software.ibm.com/sblim .
Alternatevily you can check out the GATHER_1_0_BRANCH from CVS.

About this Package
------------------
The purpose of this package is to implement the DMTF CIM Metrics Model
for Linux, making it available via a CIMOM supporting/supported by the CMPI
provider interface. 

The package consists of three parts:
1. The Gatherer Component
2. The Metric Plugins
3. The Performance Data Providers

While the Gatherer and it's plugins can be used standalone, the greatest
benefit comes from using it in conjuction with a CIM Object Manager (CIMOM)
like Pegasus (The Open Group). Basically it allows to remoteley obtain
performance information about a Linux system.
For more information about CIM and the CIM Metrics Model you are referred to
the Distributed Management Task Force (DMTF) at http://www.dmtf.org.

Requirements
------------

In order to build, install and operate this package you will need a 
contemporary (as of this writing) Linux System, like RedHat 8 or SuSE 8.x.
Furhter the following packages are required:

- Pegasus 2.2.1 (snapshot release) from http://www.openpegasus.org AND
  SBLIM CMPI Adapter 0.8.2 from http://oss.software.ibm.com/sblim
OR
- Pegasus 2.3.2 or higher

- SBLIM CMPI Base 1.2.1 or higher from http://oss.software.ibm.com/sblim

Build and install the packages above according to the instructions contained
therein before you continue.

Note: Of course the providers should work with any CIMOM supporting CMPI.

Building and Installing the Gatherer
------------------------------------

Change to the main subdirectory of this package and invoke "make". The 
gatherer and the plugins should now be compiled. It could be necessary
to change some macro values in the makefiles depending on your environment.

Performing "make install" (you have to do that with superuser rights) will
put the executables and libraries in the "/usr/local" branch of your system.
It might be necessary for you to point your PATH or LD_LIBRARY_PATH variables
to /usr/local/bin respectively /usr/local/lib.

With the command line utility "gatherctl" you can now start and stop the
gatherer (implemented by the "gatherd" program), load metric plugin libraries
and get metric values. At the moment there's no documentation about the
standalone gatherer and we suggest that you use it via the CIM interface, see
below.

Building and Installing the Performance Providers
-------------------------------------------------

Change to the provider subdirectory and invoke "make". Depending on your
environment it is likely that you have to change some makefile variables
(preferably in the env file).

Performing make install will copy the provider libraries into the Pegasus
library directory.

In order to be able to use the providers you must register them. For this
purpose a series of MOF-Files (in the provider/mof directory)
must be loaded into the CIMOMs repository.
There are also makefiles in this directory that invoke the MOF compiler.

In order to register the base classes you have to do a 
"make install -f makefile.pegasus".

Depending on the metrics you are interested in, you must do a 
"make install -f makefile.<MetricPluginName>.pegasus. Have a look at the
files in the plugin directory to see what is available there.

Using the Providers
-------------------

Before you can obtain metric values you have to start the gatherer. There's
a CIM class Linux_MetricGatherer controlling gatherer operations. Using a
CIM client, a CIM browser for instance, the methods StartService and
StartSampling have to be called in order to start gatherer processing.

Once started it is possible to enumerate instances of CIM_BaseMetricDefinition
and CIM_BaseMetricValue to get information about the system using a CIM
client application.