JRDS Setup and usage

You can also found another example on Asyd's blog about jrds

Get the last svn checkout

svn co http://jrds.svn.sourceforge.net/svnroot/jrds/trunk/ jrds

Install tomcat

sudo yum install tomcat5

jrds expect to run with at least Java 1.5, the default java from Centos is gcj 1.4.2. One should install an earlier version from Sun or Jpackages and then set JAVA_HOME

I used the method two shown on this Centos' wiki

JAVA_HOME=/usr/lib/jvm/java-1.6.0
export JAVA_HOME
cd jrds
JRDS_HOME=$PWD

Get and build rrd4j:

svn co --username guest --password '' https://rrd4j.dev.java.net/svn/rrd4j/trunk/rrd4j rrd4j
cd rrd4j
ant
cp lib/rrd4j-<version>.jar $JRDS_HOME/lib

Resolve dependancies using ivy

sudo  yum install xerces-j2
mkdir -p $HOME/.ant/lib
curl -o $HOME/.ant/lib/ivy.jar http://repo1.maven.org/maven2/org/apache/ivy/ivy/2.1.0-rc2/ivy-2.1.0-rc2.jar
cd $JRDS_HOME
CLASSPATH=$HOME/.ant/lib/ivy.jar ant resolve

Copy local.properties.sample to local.properties and edit it to suit your needs.

Build the war

ant

Build dojo if needed, but that's not mandatory

cd $DOJOSRC/util/buildscripts

./build.sh releaseName=jrds localeList=en-us mini=true profileFile=$JRDS_HOME/
      jrds.profile.js cssOptimize=comments optimize=shrinksafe action=release

cp $DOJOSRC/release/jrds/dojo/dojo-jrds $JRDS_HOME/web/dojo/dojo-jrds.js

Some probes like prc or jkstat needs external library, check the ant file and build them.

Configure /opt/jrds/config/jrds.properties with needed values.

configdir=/opt/jrds/config
rrddir=/opt/jrds/probe
logfile=/opt/jrds/log/jrds.log

If you want a quick start, just run it standalone, in daemon mode

ant jetty
mkdir -p /opt/jrds/webapp
tar xpf build/jrds.tar -C /opt/jrds/webapp
java -Djrds.propertiesFile=/opt/jrds/config/jrds.properties -jar /opt/jrds/webapp/WEB-INF/lib/boot.jar

If you have a Tomcat installation, it can be used

sudo mkdir -p /opt/jrds/config /opt/jrds/probe /opt/jrds/log
sudo chown -R $USER:tomcat /opt/jrds
cp build/jrds.war /opt/jrds/
sudo -e /etc/tomcat5/Catalina/localhost/jrds.xml

The jrds.xml content is:

<?xml verision='1.0' encoding='utf-8'>
    <Context cookies="false" debug="1" displayName="jrds" 
             docBase="/backup/jrds/webapp" path="/jrds" workDir="work/Catalina/localhost/jrds"'>
        <Parameter name="propertiesFile" value="/opt/jrds/conf/jrds.properties"/'>
</Context>

You can now start tomcat

/etc/init.d/tomcat6 start

You now generate some hosts configurations and make jrds to reload it

cd /opt/jrds/config
curl -o host1.xml 'http://localhost:8080/jrds/discover?host=host1'
curl -o host2.xml 'http://localhost:8080/jrds/discover?host=host2'
curl http://localhost:8080/jrds/reload

The root URL is /jrds for a tomcat server. On standalone mode, it's just a plain /.

The configuration is stored in five different kinds of file, the most common one is the host file, describing an host and every probe running on it, the four other are the filter file, the macro file, the view file and the sum file.

The jrds.properties files

The generic configuration file for jrds. It's a list of properties.

• configdir: the directory parsed to find xml configuration files

• logfile: where the logs are to be written.

• step: the interval (in seconds) betwen each collect. One it's choosen, it cannot be changed

• probe: where the probes files (rrd) are to be stored

• collectorThreads: how many differents hosts are collected in parallel

• libspath: a list of jar containing probes

• classpath: a list of jar or directory containing jars or that we'll be added to the classpath

• timeout: the timeout value (in seconds) for network activities

The loglevel can be choosen with the option :

loglevel=LEVEL

The level are the same as in log4j, and are, with increased verbosity :

fatal, error, warn, info, debug, trace.

Trace level should be avoided except in some rare conditions and even debug level can be quite verbose.

Log level for a specif class is set with the property :

log.LEVEL=CLASSLIST

The argument CLASSLIST is a comma separated list of Java classes.

Every properties can specified as a system property (for example on the commande line -D). When doing this, it must be prefixed with jrds. . For example you an easily debug a jetty settup using -Djrds.loglevel=debug on the commande line.

The host file

There is one file for each host, it provide the dns name for the host and all the probes. It can also contains tag definitions, macro calls and snmp parameters.

For example, create a file named host-avalon.xml in the config directory:

<?xml version="1.0" encoding="UTF-8"?>
<host name="avalon">
        <snmp community="public" version="2"/>
        <tag>webServer</tag>
        <tag>V40z</tag>
        <macro name="solarisHost" />
        <probe type="DiskIo">
            <arg type="String" value="sd1"/>
            <arg type="OID" value="1"/>
        </probe>
        <probe type="PartitionSpace">
            <arg type="String" value="/"/>
        </probe>
        <probe type="ApacheStatus" />
        <probe type="ProcessInfoExtended" >
            <arg type="String" value="apache"/>
            <arg type="String" value="httpd"/>
        </probe>
</host>

The SNMP element must be defined once if any snmp based probe is to be used. Each one can also have the snmp sub-element if the community or the version is different from the host's one.

If a SNMP probe take an argument, it's used to find find the key in a SNMP table. If the index numerical value is know to be static and persist across restart, an arg element of type OID can be added to avoid the scan of the table. For big one, like the interfaces of a switch, this can reduce the probe load on the machine.

The macro file

A macro file is used to store many probes that can be used by a host. It's used to centralize many definitions at the same time.

Example:

<macrodef name="solaris">
        <tag>solaris</tag>
        <probe type="TcpSnmp" />
        <probe type="IpSnmp" />
        <probe type="UdpSnmp" />
        <probe type="IcmpSnmp" />
        <probe type="Mem" />
        <probe type="ProcessStatusHostResources" />
        <probe type="CpuRawTimeSolaris" />
        <probe type="UcdRawSystemCounter" />
        <probe type="VMSolaris" />
        <probe type="RstatProbe4" />
</macrodef>

As they must be parsed before the host files that use them, jrds will look for them in a subdirectory of the configuration directory called macro.

Any defined macro can be used within an host with the macro element, with a name attributes used to identify the good macro definition. The snmp configuration can't be defined in a macro definition.

A macro element can take a properties list to define instantation variables. It's possible to use a macro many time with a different set of properties, that will generate different probes. Variable can be used in the label attribute or for probes argument.

For example, a macro an be defined in this way:

<macrodef name="solaris">
        <probe type="IfXSnmp" >
                <arg type="String" value="${netcard}0"/>
        </probe>
        <probe type="KstatDiskstat">
                <arg type="Integer" value="${hdd}" />
        </probe>
</macrodef>

and then used in this way:

<host name="server1">
        <macro name="solaris"> 
                <properties>
                        <entry key="netcard">bnx</entry>
                        <entry key="hd">0</entry>
                </properties>
        </macro>
</host>

The view file

When there is a great number of monitored hosts, it becomes cumbersone to browse the tree and get a good overview of the situation. To select a number of hosts and graphs, filter can be defined, that will only some hosts, using the tags as a filter, and on those hosts, only some graphs.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE view PUBLIC "-//jrds//DTD View//EN" "urn:jrds:view">
<view>
        <name>Routeur</name>
        <tag>solarisHost</tag>
        <path>.*merlin/Network.*</path>
</view>

Only hosts matching the tags will be kept, and on those hosts, only the graphs matching at least one path will be shown.

The sum file

Many graph of the same type can be easily combined into an unique graph using a sum description. Each source is defined using a patch constructed with hostname/graphname.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE view PUBLIC "-//jrds//DTD View//EN" "urn:jrds:view">
<sum name="Bandwith used">
    <element name="host1/ifx-bge0" />
    <element name="host2/ifx-bge0" />
    <element name="host3/ifx-bge0" />
</sum>

Edition the configuration

Both jrds.properties and the configurations files can be edited when jrds is up. To have the configuration reloaded, one just have to access the url http://<jrds path>/reload.

Many elements in jrds take an argument list.

An arg element take two arguments :

• The type, it's the java class of the argument, the class name without the package is enough for some common package.

• The value of the argument, the type must accept it as a String.

A special type of argument is the list that can be used to build a List object

The DTD for a argument list is :

<!ELEMENT some_element (arg, list)* >
<!ELEMENT arg EMPTY>
<!ATTLIST arg
          type CDATA #REQUIRED
          value CDATA #REQUIRED
>
<!ELEMENT list (arg, list)+ >

A properties block can be used to define variables what will be solved at run time. The variable can be used in the form ${variablename}

The properties block DTD is:

<!--from http://java.sun.com/dtd/properties.dtd -->
<!ELEMENT properties ( comment?, entry* ) >
<!ELEMENT comment (#PCDATA) >
<!ELEMENT entry (#PCDATA) >
<!ATTLIST entry key CDATA #REQUIRED>

For each probe, thresholds can be specifed that will trigger actions when a collected value will reach a level. For each threashold, the following parameters are used :

• name: a symbolic name

• dsName : the datasource to check

• value : the thresold that trigger an action

• duration : the duration (in minutes) that trigger the action

• limit : the strings high or low (case insensitive)

for each threshold, some actions can be defined, they are :

• log : add a line in the log file, it takes one argument, a log4j level.

• mail : it sends a mail, the mail parameters are specified in jrds.properties, they are :

  • action.mail.from

  • action.mail.to

  • action.mail.host

The DTD for a threshold is :

<!ELEMENT threshold (action+ ) >
<!ATTLIST threshold
          name CDATA #REQUIRED
          dsName CDATA #REQUIRED
          value CDATA #REQUIRED
          duration CDATA #REQUIRED
          limit CDATA #REQUIRED
>
<!ELEMENT action (arg, list)* >
<!ATTLIST action
          type CDATA #REQUIRED
>

After a modification of a configuration file, one needs to use this URL to reload it.

It can be used to enumera the jar used by the main classes.

Used to discover the an host configuration. It takes an argument host, which is the hostname to discover.

With the argument withoid, the index OID is added if needed.

Each argument tag is added as a tag in the result.