XmlBlaster Logo

REQUIREMENT

admin.jmx

XmlBlaster Logo


Type NEW
Priority MEDIUM
Status CLOSED
Topic XmlBlaster provides an JMX-Interface for monitoring and controlling
Des
cription

JMX overview

JMX-support (Java Management Extension) is available for xmlBlaster.
You need to pass some configuration parameters on xmlBlaster startup and you are ready to observe the running xmlBlaster from a remote GUI application.

What is JMX?

JMX is a Sun standard that allows Java developers to rapidly management functionality into existing applications.
JMX defines a standard for writing JMX objects, also called MBeans. MBeans basically represent the state and the functionality of a managed ressource. It is possible for a JMX client to invoke methods and access attributes on an MBean. A JMX Agent enables manageability of these functionalities from local or remote, allowing a system administrator to manage the components of the application.

JMX - xmlBlaster integration overview

JMX adaptor overview

XmlBlaster provides internal informations using MBean as specified by the JMX specification. To access those MBeans there are several adaptors available:

Adaptor Description GUI access
HtmlAdaptor The support is delivered ready to go with your xmlBlaster distribution and is available for JDK >= 1.3 Access xmlBlaster from any web browser
jconsole adaptor Access xmlBlaster from the jconsole adaptor. You need a JDK runtime 1.5 or newer to use jconsole. Nevertheless it is possible to compile xmlBlaster with JDK 1.4 as the adaptor is loaded by reflection. The jconsole GUI application is delivered with JDK 1.5, you don't need to install anything else. Note you can additionally access xmlBlaster with many other commercial of the shelf monitoring tools if they support JMX (for example openAdaptor).
Native xmlBlaster adaptor This support uses xmlBlaster own communication protocol listening on port 3424. The adaptor is developed by Oliver Neubert and provides a pluggable swing GUI to monitor. It is currently not functional. Within the "normal" xmlBlaster server instance another embedded xmlBlaster instance is started that handles the communication with clients. An administration client implemented with SWING is available. It can be found at org.xmlBlaster.jmxgui.
The user interface is pluggable and new plugins, handling other MBeans, can be added to the system. To show the usage, two plugins have already been added.
MX4J HTTP Adaptor Support This support uses the mx4j http jmx adaptor which can be loaded as a plugin. It is highly configurable. The adaptor itself generates xml code which can be processed by an xslt processor. This processor reads your own xsl stylesheets. We use this as a monitoring tool for Database replication.
SNMP adaptor If you need to monitor xmlBlaster from an existing SNMP aware monitoring tool you need to install a SNMP adaptor. This is currently only available under commercial licenses from SUN with the Java Dynamic Management Kit JDMK (~6000 US$) or from AdventNet with the SNMP Adaptor for JMX (~500 US$) or " target="others">Koshna SNMP Toolkit for JMX (~1200 US$) Any existing SNMP aware monitoring tool like NAGIOS or HP-OpenView can be used as front end.

Changing properties using JMX

Important note: When changing properties with JMX you need to be aware what you are doing. Not all configurations over JMX have been tested. It is best that you check any manipulation first on your reference system.

Example
any

Observing xmlBlaster with a browser

On startup of xmlBlaster you need to switch this adaptor on:

java org.xmlBlaster.Main -xmlBlaster/jmx/HtmlAdaptor true

Open URL
   http://localhost:8082
in your browser.
   

This adaptor does not support changing of property names containing '[' or ']' as it interprets those as an array. A smart work around is currently not known.

Caution: You should protect remote access of xmlBlaster using the html adaptor with a login name and password, see the configuration section below how to do it, here is an example (type all in one line):

java org.xmlBlaster.Main -xmlBlaster/jmx/HtmlAdaptor true 
                         -xmlBlaster/jmx/HtmlAdaptor/loginName admin
                         -xmlBlaster/jmx/HtmlAdaptor/password secret

Open URL
   http://localhost:8082
in your browser and type in the above credentials.
   

Note: You need the jmxtools.jar file in your CLASSPATH which is there if you use the xmlBlaster.jar as downloaded.
If you create a distribution add it like build -DADD_JMXTOOLS=true ... dist

HTML adaptor screenshot

JMX - xmlBlaster HTML adaptor browser screenshot

Example
any

Observing xmlBlaster with jconsole

# Start the server
java -Dcom.sun.management.jmxremote org.xmlBlaster.Main

# Start the GUI:
jconsole
   

You find the jconsole application in the JAVA_HOME\bin directory of JDK 1.5 or above. Start jconsole as the same user and on the same computer as the server.

In the MBeans tab of jconsole you find the org.xmlBlaster root node.

Remote access

For remote access try these settings, take care, in this setup you have no access control and anybody could log in:

# Start the server
java -Dcom.sun.management.jmxremote.port=1099
     -Dcom.sun.management.jmxremote.ssl=false
     -Dcom.sun.management.jmxremote.authenticate=false org.xmlBlaster.Main

# Start the GUI:
jconsole service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
   

Please replace localhost in the above example with your computer DNS name or IP address. Note that on Linux the command 'hostname -i' must return the remote IP address (adjust /etc/hostname).

Simple password protection

Now we add simple password protection, first we create a password file called jmxremote.password with clear text password secret and one read only and one administrative user:

# jmxremote.password
# Set permissions to be readable by xmlBlaster user only:
# Unix:
#    chmod 600 jmxremote.password
# Windows NTFS:
#    cacls jmxremote.password /P %USERNAME%:C
monitorRole secret
controlRole secret
   

There is an example password file /opt/jdk1.5.0_04/jre/lib/management/jmxremote.password.template delivered with your JDK which contains some guidance.

# Start the server
java -Dcom.sun.management.jmxremote.port=1099
     -Dcom.sun.management.jmxremote.ssl=false
     -Dcom.sun.management.jmxremote.password.file=jmxremote.password
      org.xmlBlaster.Main

# Start the GUI (and enter user=controlRole, password=secret):
jconsole service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
   

Note: For remote access of xmlBlaster using jconsole with password or SSL protection please consult the jconsole online documentation and read the jconsole FAQ.

Handcrafted JMX-RMI startup

If you don't have access to the JVM and can't set the system properties we provide a self-coded JMX-RMI adaptor startup possibility, here is an example:

java org.xmlBlaster.Main -xmlBlaster/jmx/rmi true
                         -xmlBlaster/jmx/rmi/user joe
                         -xmlBlaster/jmx/rmi/password secret

# Start the GUI (and enter user=joe, password=secret):
jconsole service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
   

Jconsole screenshot

JMX - xmlBlaster jconsole screenshot

Example
any

Observing xmlBlaster with MC4J GUI

The MC4J sourceforge project offers an advanced Management Console, here is how to start it:

java -Dcom.sun.management.jmxremote
     -Dcom.sun.management.jmxremote.port=8999
     -Dcom.sun.management.jmxremote.ssl=false
     -Dcom.sun.management.jmxremote.authenticate=false org.xmlBlaster.Main

MC4J_Console_1.2b9   (start the GUI, choose 'Create Server Connection' -> 'J2SE 5.0')
   

Note: The above example is unprotected, you definitely need to configure SSL protection!

MC4J screenshot

JMX - xmlBlaster MC4J screenshot

Example
any

Monitoring Specific Functionality with the MX4J Plugin

Uncomment the plugin in xmlBlasterPlugins.xml to activate this adaptor.


      <plugin id='MX4JAdaptorPlugin' className='org.xmlBlaster.contrib.jmx.MX4JAdaptor'>
      <attribute id="xsltProcessor">XSLTProcessor</attribute>
      <attribute id="hostname">localhost</localhost>
      <attribute id="port">9999</attribute>
      <attribute id="adaptorName">HttpAdaptorMX4J</attribute>
      <attribute id="xsltPath">org/xmlBlaster/contrib/replication/monitor</attribute>
      <attribute  id="xsltCache">false</attribute>
      <attribute  id="defaultUrl">serverbydomain</attribute>

      <!-- <attribute id="xsltLocale"></attribute> -->
      <action do='LOAD' onStartupRunlevel='4' sequence='5' onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='3' sequence='65'/>
   </plugin>

      

Start the XmlBlaster. You also need to activate one JMX Connector, either the RMI or HTTP would do it:

 java -Dcom.sun.management.jmxremote org.xmlBlaster.Main
   or
 java org.xmlBlaster.Main -xmlBlaster/jmx/HtmlAdaptor true 
   or
 java -Dcom.sun.management.jmxremote org.xmlBlaster.Main -xmlBlaster/jmx/HtmlAdaptor true 
      

This example would start an instance of an http server listening on the localhost on port 9999. For each http request, MX4J generates an XML response. If you don't specify an xsltProcessor, for example if you comment out the line:


   <!-- <attribute id="xsltProcessor">XSLTProcessor</attribute> -->

        
the adaptor will return the raw XML string. This is very useful under development to see how to write your own xsl stylesheets.

Urls to start with are (replace 'heron' in the examples with your cluster node id, here we have started xmlBlaster with -cluster.node.id heron):

  • http://localhost:9999/
  • http://localhost:9999/mbean?objectname=org.xmlBlaster:nodeClass=node,*
  • http://localhost:9999/mbean?objectname=org.xmlBlaster:nodeClass=node,*&attributes=false
  • http://localhost:9999/mbean?objectname=org.xmlBlaster:nodeClass=node,node=%22heron%22,clientClass=client,*
  • http://localhost:9999/mbean?objectname=org.xmlBlaster:nodeClass=node,node=%22heron%22,queueClass=queue,*
  • http://localhost:9999/mbean?objectname=org.xmlBlaster:queueClass=queue,*

All above queries return the 'raw' xml.

A trailing '*' returns the complete hierarchy below, a named final name returns the flat object. A missing part in the upper hierarchy is interpreted as a '*' to get all the leaves.

The next step is to apply a XSL stylesheet for nicer formatting, exampes are provided xmlBlaster/src/java/org/xmlBlaster/contrib/replication/monitor/*.xsl (serverbydomain.xsl is the entry point for others like destinationDetails.xsl). It is very helpful to have two plugins running, one for the raw xml output and the other to develop the xsl.

If you use the xsltProcessor but do not define your own stylesheets (here it would mean you erase the xsl in ${user.home}/xmlBlaster/src/java/org/xmlBlaster/contrib/replication/monitor, the default stylesheets of mx4j would be used.
Invoking http://localhost:9999 would take the default invocation which is serverbydomain.

Per default this request is processed by the own xslt processing. In our case we have specified an xsltProcessor, that is we bypass the default behaviour. In other words we will process the generated xml by own xsl stylesheets. The location of these stylesheets is defined by the parameter xsltPath. The searching mechanism for this path is different from the one provided by default by the mx4j implementation. This plugin will search for the path in the CLASSPATH. If more than such path are found in the CLASSPATH are found, then the first is taken and a warning is given once listing all other locations found.
The jmx name to be given to the adaptor is specified by the attribute adaptorName.

For each request the processor must know which stylesheet to use. Per default, if you invoke an mbean request, it will use mbean.xsl, if you make a server request, it will use server.xsl. You can overwrite the default behaviour as we do by specifying an http attribute in the get request called template. If you pass template=destinationList, then the xslt processor will look for a file called destinationList.xsl. More information you will find on the http adaptor description for mx4j.

MX4J screenshot (replication example)

mx4j

Configure

JMX is configured in the xmlBlaster.properties configuration file or on command line.

Id (name) Type Manda tory Default value Comment
java -Dcom.sun.management.jmxremote String no - If given as system property the jconsole monitoring support is switched on, the rmiregistry is expected on its default port 1099.
java -Dcom.sun.management.jmxremote.port=2209 String no - If given as system property the jconsole monitoring support is switched on, the rmiregistry uses the given port.
xmlBlaster/jmx/rmiregistry/jndiPath String no /jmxrmi In a cluster environment where different xmlBlaster instances use the same rmiregistry you need to distinguish the instances.
The cluster.node.id could be a nice unifier: "/jmxrmi/"+${cluster.node.id}
xmlBlaster/jmx/rmi bool no false If set to true the jconsole monitoring support is switched on, in this case we have implemented the startup overselve. This is useful if you don't have control on the JVM and can't set java -Dcom.sun.management.jmxremote properties on JVM startup. For example the wrapper.exe (Windows service registration) does not set the system properties early enough.
Please add -xmlBlaster/jmx/rmi/user joe and xmlBlaster/jmx/rmi/password secret credentials for access authentication.
xmlBlaster/jmx/rmiregistry/hostname String no localhost Set the host of the rmiregistry server.
xmlBlaster/jmx/rmiregistry/port int no 1099 Set the port of the rmiregistry server.
xmlBlaster/jmx/rmiserver/hostname String no localhost Force the host of the RMIServer and RMIConnection remote objects
xmlBlaster/jmx/rmiserver/port int no 6011 Force the port of the RMIServer and RMIConnection remote objects
xmlBlaster/jmx/HtmlAdaptor bool no false HTML adaptor: Switch on with 'true'.
xmlBlaster/jmx/HtmlAdaptor/hostname String no localhost HTML adaptor: Configures the hostname, where to listen for HTTP requests.
xmlBlaster/jmx/HtmlAdaptor/port int no 8082 HTML adaptor: Configures the port, where to listen for HTTP requests.
xmlBlaster/jmx/HtmlAdaptor/loginName String no null HTML adaptor: If given the access is restricted to the given user
xmlBlaster/jmx/HtmlAdaptor/password String no secret HTML adaptor: The password, needed only if xmlBlaster/jmx/HtmlAdaptor/loginName!=null
xmlBlaster/jmx/XmlBlasterAdaptor bool no false XmlBlaster native adaptor: true switches it on.
xmlBlaster/jmx/observeLowMemory bool no true Since JDK 1.5: If true we check for critical RAM usage.
xmlBlaster/jmx/memoryThresholdFactor float no 0.9 Since JDK 1.5: If the RAM of the JVM is used up to 90% we will log an error.
xmlBlaster/jmx/exitOnMemoryThreshold bool no false Since JDK 1.5, if changed to true: If xmlBlaster/jmx/memoryThresholdFactor is hit xmlBlaster will shutdown.

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

Todo
  1. Write some test cases
  2. Fix native XmlBlaster adaptor
  3. Strip down embedded xmlBlaster to minimum
  4. Write some jmxgui plugins
  5. Find a free SNMP adaptor
  6. Analyze if we need more notifications
  7. Add client observation (C/C++/Java clients over internal messages)
  8. Fix XmlBlasterException (-> Exception)
  9. Add attribute help, see descriptions like TopicHandlerMBeanDescription in http://mx4j.sourceforge.net/docs/ch04.html or XDoclet http://mx4j.sourceforge.net/docs/ch07s15.html#N11001
  10. Add ManageEngine example, connected over MX4J RMI connector
  11. Consider to use http://jakarta.apache.org/commons/modeler/ to avoid MBean base interfaces
See REQ admin.commands
See REQ admin.events
See API Node specific usage details
See API Subject specific usage details
See API Session specific usage details
See API Topic specific usage details
See API Subscription specific usage details
See API Queue specific usage details
See API Storage specific usage details
See JMX homepage
See JMX guide
See JMX tips
See JMX tech-article
See JMX Understand jconsole
See MX4J Open Source implementation of JMX
See JMDK homepage
See MC4J homepage

This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.jmx.xml

Back to overview