MBeanCmd 2.1

User's guide

JASMINe Team

OW2 consortium

This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

$Id: mbeancmd_guide.xml 3096 2009-02-06 15:21:52Z alitokmen $

Chapter 1. Introduction

MBeanCmd is a command-line tool written in Java for interacting with MBeans on any J2EE server.

It can :

Send commands to :
- Any number of MBeans
- On any number of J2EE servers
- In a periodical way
Receive the result of that command, for example the CPU usage rate measured by the JVM mbean
Use this result to :
- Display it directly on the console
- Output it to a text file
- Display it on a graph
- Push it to a JASMINe Event Switch

It does not depend on any J2EE package. The various outputs (for example, file, graph and JASMINe Event Switch) can be combined.

Chapter 2. MBeans and your J2EE server

2.1. What is an MBean ?
2.2. MBeans in JOnAS
2.3. Connecting to MBeans on a J2EE server

2.1. What is an MBean ?

MBeans are managed beans, i.e. Java objects that represent resources to be managed. An MBean has a management interface consisting of:

Named and typed attributes that can be read and written
Named and typed operations that can be invoked
Typed notifications that can be emitted by the MBean

For example, an MBean representing an application's configuration could have attributes representing the different configuration parameters, such as a cache size.

2.2. MBeans in JOnAS

Getting to the list of available MBeans in JOnAS is pretty straightforward, thanks to the JOnAS Administration interface: simply click on MBeans on the menu on the left and the list of currently deployed MBeans will appear.

2.3. Connecting to MBeans on a J2EE server

Note that not all those MBeans are available remotely: to connect to any MBean, one needs to use a connector MBean. To get the list of the connector MBeans and their addresses in JOnAS, click on Other MBeans - Connectors. In the Attibutes tab of a connector MBean, you can see its JMX Service URL:

Chapter 3. Using MBeanCmd

3.1. Getting help

3.2. Defining targets

3.3. The Poll command

3.4. The Stat command

3.5. The JDBC Connections command

3.6. The Dump command

3.7. The Snap command

3.8. The Scan command

3.9. The WildStat command

3.10. Example: output the number of threads

3.10.1. On the console
3.10.2. On a spreadsheet
3.10.3. In a graph

3.1. Getting help

To launch MBeanCmd, just go to the folder where mbean.jar is present and launch :

java -jar mbean.jar

Since no option has been specified, this will simply display the help.

To display the help for a command, say poll, type in :

java -jar mbean.jar help poll

	Note
	Note that the help file for poll is quite large: it includes the usage options and the DTD to use to display a graph.

3.2. Defining targets

To use MBeanCmd for capturing statistics periodically (poll and stat commands) or to get a thread dump from a JOnAS server (dump command), you first need to define which J2EE server(s) you're targeting. This can be done in two ways:

If you're targeting only one server, define jasmine.jmx.url to the connector's URL.

If you're targeting multiple servers, create a file called jmxurls.properties (file name can be changed by redefining jasmine.jmx.file). This file contains the list of servers and the default target. For example:

jasmine.jmx.url.j1 = service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas0
jasmine.jmx.url.j3 = service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas1
jasmine.jmx.url.j2 = service:jmx:rmi:///jndi/rmi://192.168.7.5:1099/jrmpconnector_jonas
jasmine.jmx.default.target = j1

You can also define user name and passwords to use for the JMX connection to each of the J2EE Server instances. For example:

jasmine.jmx.user.j1=john.smith
jasmine.jmx.password.j1=p4ssw0rd

Example 3.1. -target option use

poll ... -target all

poll ... -target j1 j2

poll ... -target j1 j3 j5

The "all" target stands for all the targets defined by the property file plus the jasmine.jmx.property.

	Note
	If no target is defined, the url service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas will be used by default. For several commands (as poll -cpusun), the targeted servers need to be launched with the system property com.sun.management.jmxremote, in order to enable the monitoring of this JVM by JMX.

3.3. The Poll command

poll [-p period] [-s separator] bean [OUTPUT] [TARGET]

-p period : Sets the period in seconds. Default value is 10
-s separator : Sets the separator. Default is ";"
bean : must be one of the following
- -server : Prints overall statistics.
- -http : Prints statistics on HTTP/AJP connectors (one line per connector).
- -tx : Prints statistics on transactions.
- -cpusun : Prints statistics on the CPU usage.
- -ds FILTER : Prints statistics on datasources.
- -jcacf FILTER : Prints statistics on JCA connection factories.
- -slb FILTER : Prints statistics on stateless session EJBs.
- -sfb FILTER : Prints statistics on stateful session EJBs.
- -ent FILTER : Prints statistics on entity session EJBs.
- -servlet FILTER : Prints statistics on servlets.
- -joramq FILTER : Prints statistics on JORAM queues. The domain in FILTER shall be joramClient.
OUTPUT

The command prints statistics into stdout, unless the -f or -jasmine option is set. The -f, -graph and -jasmine options are not exclusive.
- -f FILE : Causes the output to be redirected to FILE.
- -graph XML_DEF : Displays graphs according to the XML definitions specified by the XML_DEF file.
- -jasmine URL : Causes the output to be redirected to the JASMINe Event Switch located at URL.
TARGET

See Section 3.2, “Defining targets”

Table 3.1. Attributes polled

Option	Indicators
-tx	*:j2eeType=JTAResource,* => totalCurrentTransactions, totalCommittedTransactions, totalRolledbackTransactions, totalExpiredTransactions
-tx	processed => txRate, commitRatio, currentCommitRatio
-http	*:type=Manager,* => activeSessions, sessionCounter
	*:type=GlobalRequestProcessor,* => requestCount, errorCount, processingTime, maxTime, bytesSent, bytesReceived
	*:type=ThreadPool,* => currentThreadsBusy
	processed => bytesReveivedRate, byteSentRate
-ds	*:j2eeType=JDBCDataSource,* => currentOpened, currentBusy, currentInTx, busyMin, busyMax, jdbcMinConnPool, jdbcMaxConnPool, jdbcConnMaxAge, openedCount, connectionFailures, MaxOpenTime, connectionLeaks, jdbcMaxWaiters, currentWaiters, waitersHighRecent, waitersHigh, waiterCount, jdbcMaxWaitTime, waitingHigh, waitingHighRecent, waitingTime, servedOpen, Open, rejectedFull, rejectedTimeout, rejectedOther, jdbcSamplingPeriod
-ent	*:j2eeType=EntityBean,* => name, cacheSize, poolSize, entityCounters, maxCacheSize, minPoolSize
-slb	*:j2eeType=StatelessSessionBean,* => name, cacheSize, poolSize, minPoolSize, maxCacheSize, sessionTimeOut
-sfb	*:j2eeType=StatefulSessionBean,* => name, cacheSize, poolSize, minPoolSize, maxCacheSize, sessionTimeOut
-servlet	*:j2eeType=Servlet,* => requestCount, errorCount, processingTime, maxTime, minTime
-cpusun	java.lang:type=OperatingSystem => ProcessCpuTime
-cpusun	processed => currentCpuTime, currentCpuLoad

Example 3.2. Poll command examples

poll -ds "*:j2eeType=JDBCDataSource,*"

poll -slb "*:j2eeType=StatelessSessionBean,J2EEApplication=myApp,*"

poll -sfb "*:j2eeType=StatefulSessionBean,J2EEApplication=myApp,*"

poll -ent "*:j2eeType=EntityBean,J2EEApplication=myApp,*"

poll -servlet "*:j2eeType=Servlet,J2EEApplication=myApp,*"

poll -joramq "joramclient:type=queue,*"

3.4. The Stat command

stat [-p period] [-r period] [-s separator] [-name filter] [-a attribute] [OUTPUT] [TARGET]

-p period : Sets the period in seconds. Default value is 10
-r period : Sets the the period for rebuilding the list of mbeans to poll. Default value is 300
-s separator : Sets the separator. Default is ";"
-name filter : Defines the mbeans to poll. FILTER may be an exact match of a mbean or contains wildcards according to the JMX conventions.

Example : stat -name "joramClient:type=queue,*"
-a attribute : Sets the list of attributes to poll. If no attribute is specified, the attribute list is guessed from the first queried mbean.
OUTPUT

The command prints statistics into stdout, unless the -f or -jasmine option is set. The -f, -graph and -jasmine options are not exclusive.
- -f FILE : Causes the output to be redirected to FILE.
- -graph XML_DEF : Displays graphs according to the XML definitions specified by the XML_DEF file.
- -jasmine URL : Causes the output to be redirected to the JASMINe Event Switch located at URL.
TARGET

See Section 3.2, “Defining targets”

3.5. The JDBC Connections command

jdbcconnections [-o file] [-d duration] [-n datasource-name] [TARGET]

-o -output-file <filename>: Print the result in the given file.
-d -duration-filter <duration>: Filter connection opened for more than <duration-filter> seconds.
-n -datasource-name <name>: ObjectName of the DataSource to be observed.
TARGET

See Section 3.2, “Defining targets”

Unless specified by the jasmine.jmx.url property, the default target is :

service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas

Example 3.3. JDBC Connection status

from resource service

java -jar mbeancmd.jar jdbcconnections -n jonas:j2eeType=JCAConnectionFactory,name=jdbc_1,JCAResource=db_access_jdbc1,J2EEServer=jonas

from dbm service

java -jar mbeancmd.jar jdbcconnections -n jonas:j2eeType=JDBCDataSource,name=HSQL1,JDBCResource=JDBCResource,J2EEServer=jonas

3.6. The Dump command

dump [-f file] [-l] [TARGET]

-f, -file filename : Prints thread stack dump in a given file "filename"
-l, -log :Prints thread stack dump in JOnAS log file (level: info)

Example : dump -f /home/username/threaddump.txt
TARGET

See Section 3.2, “Defining targets”

3.7. The Snap command

snap -name FILTER -a attributes [ -s attributes ] [ -delta [ time_interval ] ] [ -z ] [ -m up | down ] [TARGET]

This command is useful to figure out what is going on on a set of JOnAS (or JVM instances). Use this command if you have no preconceived idea of what instance does what. It enables for example to pinpoint which servlets of which JOnAS instances are intensively requested, which EJBs take the most processing time, which instances have an intense transactionnel activity, which JVM have a high workload to do (many active threads). it can be used to audit a production site before setting up further stat or poll commands.

-name FILTER : a mbean pattern, as defined by the JMX Specification. Example: to collect data on servlets, specify the FILTER as "*:j2eeType=Servlet,*".
-a atributes : the names of the attributes to collect.

-s atributes : the names of the attributes used for sorting the output. If absent, the first attribute of the -a option is used for sorting. If several attributes are supplied, they will be successively (and independently) used, and the command will print as many reports as "sort" attributes spefified by the -s option.

Example 3.4. The Snap -s option

On a "freshly started" JOnAS instance, where an administrator has connected to through the jonasAdmin console, the following command :

snap -name "*:j2eeType=Servlet,*" -a requestCount processingTime

produces the following output :

requestCount;source;mbean
27;j01;jasmine01:j2eeType=Servlet,name=default,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
3;j01;jasmine01:j2eeType=Servlet,name=action,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.welcomeContent_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.index_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.frameright_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01

whereas the following command :

snap -name "*:j2eeType=Servlet,*" -a requestCount processingTime -s requestCount processingTime

produces the following output (it first prints a list of mbeans by decreasing requestCount, then by decreasing processingTime):

requestCount;source;mbean
27;j01;jasmine01:j2eeType=Servlet,name=default,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
3;j01;jasmine01:j2eeType=Servlet,name=action,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.welcomeContent_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.index_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
1;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.frameright_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01

processingTime;source;mbean
2494;j01;jasmine01:j2eeType=Servlet,name=action,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
370;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.index_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
100;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.welcomeContent_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
70;j01;jasmine01:j2eeType=Servlet,name=default,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01
60;j01;jasmine01:j2eeType=Servlet,name=org.apache.jsp.frameright_jsp,WebModule=//localhost/jonasAdmin,J2EEApplication=none,J2EEServer=jasmine01

-delta [ time_interval ] : this option affects the snap behaviour. The command takes a baseline snapshot, then wait for time_interval seconds (default is 60 seconds), then takes a current snapshot. Then it computes the differences between the current and baseline snapshots, and orders according to the differences rather than the current values.

Example 3.5. The Snap -d option

Assume that within a slice of one minute, only the earsample application has been used. The following command :

snap -name "*:j2eeType=Servlet,*" -a requestCount processingTime -s requestCount processingTime -delta

produces the following output :

requestCount;source;mbean
                    84.0;j01;jasmine01:j2eeType=Servlet,name=default,WebModule=//localhost/earsample,J2EEApplication=earsample,J2EEServer=jasmine01
                    19.0;j01;jasmine01:j2eeType=Servlet,name=Op,WebModule=//localhost/earsample,J2EEApplication=earsample,J2EEServer=jasmine01
                    
                    processingTime;source;mbean
                    1012.0;j01;jasmine01:j2eeType=Servlet,name=Op,WebModule=//localhost/earsample,J2EEApplication=earsample,J2EEServer=jasmine01
                    30.0;j01;jasmine01:j2eeType=Servlet,name=default,WebModule=//localhost/earsample,J2EEApplication=earsample,J2EEServer=jasmine01

-z : the snap command does not print zero value, unless this option is set.
-m up | down : set the ordering mode: by increasing values (up), or by decreasing values (down). Default mode is down.
TARGET

See Section 3.2, “Defining targets”

3.8. The Scan command

scan -a attributes [ -i path ] [ -current | -delta | -stat ] [ -z ] [ -m up | down ] [ -s separator ]

This command serves the same purpose as the snap command, but unlike snap, it is for offline usage. It processes the output of the poll or stat command, either from the standard input or from a file. The first line of the input (or file) is interpreted as a header of semicolon (";") separated field (or attribute) names. Subsequent lines are parsed and field values are retrieved from their position.

A metric corresponds to a record in the input (that is, a line). it is identified by the source (that represents a JVM instance), a mbean name within the source, and comprises of a set of attributes (or fields). The source is the "sname" field, the mbean is the "mbean" field. Timestamp are retrieved from the "time" field.

-a atributes : the names of the attributes (or field) to collect.
-i path : forces scan to process a file rather than the standard input.
-s separator : forces scan to use the supplied field separator instead of the default one (semicolon ";").
-z : the scan command does not print zero value, unless this option is set.
-m up | down : set the ordering mode: by increasing values (up), or by decreasing values (down). Default mode is down.
-current : The command processes the input and retains the most recent values for each metric. This option is useful when attributes are counters.
-delta : the command builds a baseline from the first values retrieved from the input, then scan the input and retains the most recent values, then computes the variation from the baseline. this option is useful when attributes are counters.
-stat : Processes the input and computes statistics for each attribute. Sort on mean values. Computed statistics are:
- the average value for the whole scan.
- the average value of non null values.
- the minimal non null value.
- the maximal value.
- the time interval of the scan.
- the time where values are not null during the scan.
- the ratio between both times ( <=1).
This option is useful for both counter and gauges attributes.

	Note
	The -current, -delta and -stat options are mutually exclusive.

Example 3.6. The Scan command

The following command

scan -i tx.log -a commit

produces the following output:

commit;range;source;mbean
                        56996.0;4.8;jonas01;jonas01:J2EEServer=jonas01,j2eeType=JTAResource,name=JTAResource
                        24546.0;4.4;jonas02;jonas02:J2EEServer=jonas02,j2eeType=JTAResource,name=JTAResource
                        5758.0;3.8;jonas03;jonas03:J2EEServer=jonas03,j2eeType=JTAResource,name=JTAResource

Example 3.7. The Scan command : -delta option

The following command (with the -delta option)

scan -i tx.log -a commit -delta

produces the following output:

commit;range;source;mbean
                        47199.0;4.7;jonas01;jonas01:J2EEServer=jonas01,j2eeType=JTAResource,name=JTAResource
                        4095.0;3.6;jonas02;jonas02:J2EEServer=jonas02,j2eeType=JTAResource,name=JTAResource

jonas03 is no more listed, as no transaction has been committed on it while the tx.log file was recorded.

3.9. The WildStat command

wildstat [-p period] [-r period] [-s separator] BEAN [-a attributes] [-c config] [-q query] [OUTPUT] [TARGET]

This command allows you to launch an MBeanCmd command using the features offers by WildCAT. WildCAT permits to build a hierarchical context in which you can organize datas and query for operations like aggregation and filtering.

	Note
	This command is only available in the distribution `mbeancmd-wildstat`. This is due to a licence limitation of Esper, the Complex Event Processing engine on which WildCAT is based.

-p period : Sets the period in seconds.
-r period : Sets the the period for rebuilding the list of mbeans to poll. Default refresh period is 300 seconds.
-s separator : Sets the separator. Default is ";".
BEAN

-name filter : Defines the mbeans to poll. filter may be an exact match of a mbean or contains wildcards according to the JMX conventions.
-a attributes : Sets the list of attributes to poll. If no attribute is specified, the attribute list is guessed from the first queried mbean.
-c config : Sets the configuration file for WildCAT.
-q query : Sets an Event Query to aggregate or filter results. Notice that aggregated fields have to be the name prefixed by "my". default : select * from org.ow2.jasmine.event.attribute.JasmineAttributeChangedEvent

Note

the query language is EPL (Esper Processing Language). You can find documentation on it here.
OUTPUT

The command prints statistics into stdout, unless the -f or -jasmine option is set. The -f, -graph and -jasmine options are not exclusive.
- -export : export the result in the WildCAT context defined in de configuration file (cf. -c option). The result will be sent in self://jasmine/mbeancmd#wildstat.
- -f FILE : Causes the output to be redirected to FILE.
- -graph XML_DEF : Displays graphs according to the XML definitions specified by the XML_DEF file.
- -jasmine URL : Causes the output to be redirected to the JASMINe Event Switch located at URL.
TARGET

See Section 3.2, “Defining targets”

Example 3.8. The WildStat command examples

wildstat -p 10 -r 300 -name "joramClient:type=queue,*" -c standalone.properties -q "select * from org.ow2.jasmine.event.attribute.JasmineAttributeChangedEvent(value>=100)" -target all -jasmine vm://JasmineEventDispatcher

wildstat -q "select domain, server, objectName, probe, sname, avg(cast(value,int)) as value from org.ow2.jasmine.event.attribute.JasmineAttributeChangedEvent.win:time(10 sec) group by domain, server, objectName, probe, sname"

3.10. Example: output the number of threads

If we browse the JOnAS Administration interface, we see that the JVM J2EE Bean (called in our case jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas ) has an attribute called allThreadsCount (The number of active threads in the JVM).

We'll now output this information on different mediums.

3.10.1. On the console

We know that:

We'll be targeting only one server
The IP address of the targeted server is 129.183.101.109
The JOnAS Administration interface tells the JRMP MBean connector is on service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas
We want a refresh period of 1 second

Therefore, the command to launch is:

java -Djasmine.jmx.url=service:jmx:rmi:///jndi/rmi://129.183.101.109:1099/jrmpconnector_jonas -jar mbean.jar stat -p 1 -name "*:j2eeType=JVM,*" -a allThreadsCount

This displays the following output:

date;time;sname;server;domain;mbean;allThreadsCount
2007/12/21 11:03:22;1198231402118;jonas;jonas;jonas;jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas;125
2007/12/21 11:03:23;1198231403194;jonas;jonas;jonas;jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas;126
2007/12/21 11:03:24;1198231404254;jonas;jonas;jonas;jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas;123
2007/12/21 11:03:25;1198231405313;jonas;jonas;jonas;jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas;130
2007/12/21 11:03:26;1198231406373;jonas;jonas;jonas;jonas:j2eeType=JVM,name=jonas,J2EEServer=jonas;126
[etc]

On that output, you'll notice that:

The first row of data contains the list of attributes
All other rows contain the sampled data using the format specified in the first row

3.10.2. On a spreadsheet

Since any spreadsheet software can read comma separated values, it is rather trivial to import data captured by MBeanCmd into a spreadsheet: just copy and paste the console output:

3.10.3. In a graph

The -graph option can be used to display the sampled data in a graph. The XML DTD of a graph can be accessed by typing:

 java -jar mbean.jar help stat

 java -jar mbean.jar help poll

To display the number of threads in a simple graph, the following graph.xml file can be used:

java -Djasmine.jmx.url=service:jmx:rmi:///jndi/rmi://129.183.101.109:1099/jrmpconnector_jonas -jar mbean.jar stat -p 1 -graph graph.xml -name "*:j2eeType=JVM,*" -a allThreadsCount

Which will display the following graph:

Note that you can also display multiple series on one graph.

Chapter 4. MGen - a configuration generator for MBeanCmd

4.1. Pre-Requisites

4.2. MGen setup

4.2.1. Tree structure
4.2.2. Compile MGen

4.3. mgen-conf.xml ... scheme summary of THE file

4.3.1. "vars" section
4.3.2. "components" section
4.3.3. "servers" section

4.1. Pre-Requisites

We will assume that we want to monitor a JOnAS cluster, and that we have got a working compiled version of MBeanCmd in the following path : $MGEN_ROOT/../dist/mbean.jar.

4.2. MGen setup

4.2.1. Tree structure

Here stands the tree structure of the "mgen" repertory.

The mgen-conf.xml file enables you to set the details you want to monitor. In the following example, the CPU load is switched on.

<?xml version='1.0' encoding='ISO-8859-1' ?>
<mgen-conf>
  <global>
    <vars> 
      <var id="APPCTX">/sampleCluster2</var> 
      <var id="J2EEAPP">sampleCluster2</var>
      <var id="DSAPP">jdbc_1</var>
    </vars>

    <components> 
      <component id="cpusun">
        <cmd-unix>poll -cpusun</cmd-unix> 
        <cmd-win>poll -cpusun</cmd-win> 
        <series> 
          <serie id="currentCpuLoad" title="currentCpuLoad" col="currentCpuLoad" type="double"/> 
        </series> 
        <graphs> 
          <graph id="g1" title="CPU Load"> 
            <serie id="currentCpuLoad"/>
          </graph> 
        </graphs> 
      </component>
    </components> 
  </global> 
  
  <servers> 
    <server>
      <name>jonas</name> 
      <host>localhost</host>
      <port>1099</port>
      <protocol>jrmp</protocol>
    </server>
  </servers> 
</mgen-conf>

The "components" section describes all the indicators we want to supervise. For each, the unix and windows MBeanCmd commands are described, as well as the description of the graph. The main part of the section is the "series" one, where we can define which indicators we want to monitor. Finaly, the "servers" section is where we setup on which JOnAS server we are going to do the monitoring.

The "output" directory contains all the files generated by the ant script. In the "dist" directory stands the file mbean.jar, which is a simple copy of of the file $MGEN_ROOT/../dist/mbean.jar. The "graphs" directory contains the xml graph description files parsed by the grapher to make all the graphs we asked for. "monitoring.sh" script launch all the mbeancmd scripts contained in the "scripts" repertory. We can obviously lauch those scripts one by one.
The "styles" repertory contains all the xsl files used for generating the configuration.
The "templates" directory, where mbeancmd environment variables are contained.

4.2.2. Compile MGen

Nothing to be scared of, just run "ant" in a command line. This will ask us for the repertory name to put the result in (default is ./output/). Generated files have been seen in the previous section.

4.3. mgen-conf.xml ... scheme summary of THE file

4.3.1. "vars" section

Here we can define some variables we may require in the next sections. Typically, the variable may be associated with the application context. Just take a look on the following example :

<?xml version='1.0' encoding='ISO-8859-1' ?> 
<mgen-conf>
  <global> 
    <vars> 
      <var id="APPCTX">/sampleCluster2</var> 
    </vars>
  
    [...]
  
    <components> 
      <component id="session">
        <cmd-unix>stat -name *:type=Manager,path=$APPCTX,* -a name activeSessions sessionCounter expiredSessions</cmd-unix>
        <cmd-win>stat -name &amp;quot;*:type=Manager,path=%APPCTX%,*&amp;quot; -a name activeSessions sessionCounter expiredSessions</cmd-win>
        [..]

The variable APPCTX will be replaced by its value when the file will be parsed. We can define as many variables as we want to.

4.3.2. "components" section

This is where all the components we want to monitor are defined. Here is a good example of what a component description could be :

<component id="tx"> 
  <cmd-unix>poll -tx</cmd-unix>
  <cmd-win>poll -tx</cmd-win> 
  
  <series> 
    <serie id="txRate" title="Rate" col="txRate" type="double"/> 
    <serie id="pending" title="Pending" col="pending" type="double"/>
    <serie id="commit" title="Commits" col="commit" type="double"/> 
    <serie id="rollback" title="Rollbacks" col="rollback" type="double"/> 
    <serie id="timedOut" title="Timeouts" col="timedOut" type="double"/> 
    <serie id="commitRatio" title="Mean commit ratio" col="commitRatio" type="double"/> 
    <serie id="currentCommitRatio" title="Current commit ratio" col="currentCommitRatio" type="double"/>
  </series> 
  
  <graphs> 
    <graph id="g1" title="Transactions en cours"> 
      <serie id="txRate"/> 
      <serie id="pending"/>
    </graph> 
    <graph id="g2" title="Rollbacks"> 
      <serie id="rollback"/> 
      <serie id="timedOut"/> 
    </graph>
    <graph id="g3" title="Commit ratio"> 
      <serie id="commitRatio"/> 
      <serie id="currentCommitRatio"/>
    </graph> 
    <graph id="g4" title="Nb Transactions">
      <serie id="commit"/> 
    </graph> 
  </graphs>  
</component>

Each component is identified with a unique id. There are then three main parts :

The first part is where the commands of MBeanCmd are set, both for unix and windows systems.
The second part deals with the series to get from the option given to MBeanCmd. A serie should have an unique "id", a "title", a "col" name and finaly the type that will be set to expose the data.
Finaly, the "graphs" section defines the graph we want to draw, according to the series set before. In this example, four graphs will be drawn.

4.3.3. "servers" section

This is the last section of the file, where the servers to connect on are set. The following example shows two JOnAS server connections, one with authentification and the other without. We can define the "name" of the node, the "host" and the "port" number as well as the "protocol" to use. "user" and "password" are to be used only if the JMX authentification is set.

<servers> 
  <server> 
    <name>node1</name>
    <host>localhost</host> 
    <port>2002</port>
    <protocol>jrmp</protocol> 
  </server> 
  <server>
    <name>node2</name> 
    <host>localhost</host>
    <port>2022</port> 
    <protocol>jrmp</protocol>
    <user>jonas</user>
    <password>jonas</password> 
  </server>
</servers>

	Note
	the query language is EPL (Esper Processing Language). You can find documentation on it here.