HtmlAdaptorServer, A JMX Agent with HTML Presentation for WebLogic

In this article, I presented a little utility based on the SimpleHTTPServer jython module to visualize into an HTML page a WebLogic server’s configuration and run-time mbeans. I also mentioned that there are lots other tools out there for this purpose, albeit more aimed at run-time monitoring rather than viewing the configuration mbeans. Here, I’d like show another such tool, actually a java package to install in the target JVM. As such, it is a bit more intrusive but not that much. The package is called HtmlAdaptorServer. It can be downloaded from Oracle as the archive jmx-1_2-ri.zip and its library file jmxtools.jar added to the WebLogic server’s CLASSPATH. Once connected to the target’s JMX server as a JMX agent, it can be accessed from a browser through http on the specified port (default 8082) and the target’s run-time mbeans along with their properties can be displayed, and even edited if Read-Write. In addition, some mbeans methods can also be called.

Let’s see how to use it in the context of a WebLogic domain.

Installation

The installation is quick and easy: just download the archive jmx-1_2-ri.zip from Oracle and extract its library jmxtools.jar:

# get the jmx v1.2.1 reference implementation;
export work_dir=~/HtmlAdaptorServer
mkdir $work_dir
cd $work_dir
wget https://download.oracle.com/otn-pub/java/jmx/1.2-ri/jmx-1_2-ri.zip

# extract the relevant jar;
unzip -x ./jmx-1_2_1-ri.zip jmx-1_2_1-bin/lib/jmxtools.jar

Now, we need some code to connect the HTML Adaptor to the JMX server. It can also be run later as a stand-alone program, which is handy for testing it.

# save the class startHtmlAdaptor;
cat - <<eoj > startHtmlAdaptor.java
import java.lang.management.*;
import javax.management.*;
import com.sun.jdmk.comm.HtmlAdaptorServer;

public class startHtmlAdaptor{
  public static void main(String[] args) {
     int HtmlAdaptorPort;
     System.out.println("In startHtmlAdaptor ... ");
     MBeanServer mbean_server = ManagementFactory.getPlatformMBeanServer();
     try {
         if (args.length >= 1)
            HtmlAdaptorPort = Integer.parseInt(args[0]);
         else
            HtmlAdaptorPort = 8082;
         HtmlAdaptorServer adapter = new HtmlAdaptorServer();
         ObjectName adapterName = new ObjectName("com.HTMLbrowsing.jmx:name=htmladaptor,port=" + HtmlAdaptorPort);
         adapter.setPort(HtmlAdaptorPort);
         mbean_server.registerMBean(adapter, adapterName);
         System.out.println("starting HTML Adaptor agent on port " + HtmlAdaptorPort);
         adapter.start();
     } catch (Exception e) {
       e.printStackTrace();
     }
  }
}
eoj

# let's compile it;
export CLASSPATH=.:`pwd`/jmx-1_2_1-bin/lib/jmxtools.jar
javac startHtmlAdaptor.java

Testing

In order to test it, let’s simply execute it. It will connect to its own JVM’s JMX server:

$ java -cp .:jmxtools-1.2.1.jar startHTMLAgent 8881
starting the JMX agent... 
starting HTML browsing on port 8881

Point your browser on http://localhost:8881. You’ll see the agent view below:

You can move around and notice that some properties are read-only while some others are read-write. Also, methods are presented that can be given parameters, if needed, and invoked.

Installation in a WebLogic domain

If the stand-alone agent works well, let’s move on with the installation in a WebLogic server. For our test, we’ll use the demo WebCenter domain available from Oracle as a downloadable VM. This domain uses WebLogic 12.2.1 and contains 3 managed servers in addition to the administration server. We’ll install the HtmlAdaptorServer JMX agent as a startup class so it connects to the each server’s JMX server and instrumentalize it. As it is a bit boring to manually edit the configuration from the administration console, let’s use the scripting tool wlst do do that by just copying and pasting the statements below:

# install it and the jmxtool in wl domain, here webcenter for testing;
export DOMAIN_BASE=/oracle/domains
export DOMAIN_HOME=${DOMAIN_BASE}/webcenter
export APPLICATIONS_HOME=${DOMAIN_BASE}/applications/webcenter
cp startHtmlAdaptor.class ${APPLICATIONS_HOME}/.
cp jmx-1_2_1-bin/lib/jmxtools.jar ${APPLICATIONS_HOME}/.

# start wlst;
cd ${DOMAIN_HOME}
. bin/setDomainEnv.sh
${COMMON_COMPONENTS_HOME}/common/bin/wlst.sh

# connect to the administrative server;
connect('weblogic', 'welcome1', 't3://localhost:7001/console')
edit()
startEdit()

# install the startup class on all the 4 servers to browse with distinct adaptor ports starting with 6000 and up to 6003;
# for the AdminServer;
cd('/StartupClasses')
create('startHtmlAdaptor-AdminServer', 'StartupClasses')
cd('startHtmlAdaptor-AdminServer')
cmo.setClassName('startHtmlAdaptor')
cmo.setArguments('6000')
cmo.addTarget(getMBean('/Servers/AdminServer'))

# for the IBR_server1;
cd('/StartupClasses')
create('startHtmlAdaptor-IBR_server1', 'StartupClasses')
cd('startHtmlAdaptor-IBR_server1')
cmo.setClassName('startHtmlAdaptor')
cmo.setArguments('6001')
cmo.addTarget(getMBean('/Servers/IBR_server1'))

# for the UCM_server1;
cd('/StartupClasses')
create('startHtmlAdaptor-UCM_server1', 'StartupClasses')
cd('startHtmlAdaptor-UCM_server1')
cmo.setClassName('startHtmlAdaptor')
cmo.setArguments('6002')
cmo.addTarget(getMBean('/Servers/UCM_server1'))

# for the WC_Portal;
cd('/StartupClasses')
create('startHtmlAdaptor-WC_Portal', 'StartupClasses')
cd('startHtmlAdaptor-WC_Portal')
cmo.setClassName('startHtmlAdaptor')
cmo.setArguments('6003')
cmo.addTarget(getMBean('/Servers/WC_Portal'))

# save and exit;
save()
activate()
exit()

The stand-alone program above must now be added to the domain’s CLASSPATH so it can be accessed. We use the domain’s setUserOverrides.sh script for it is sourced automatically by the other WebLogic scripts of the domain when they are executed.

# add the new class startHtmlAdaptor.class to the CLASSPATH;
cat - >> ${DOMAIN_HOME}/bin/setUserOverrides.sh
export CLASSPATH=${APPLICATIONS_HOME}/jmxtools.jar:${APPLICATIONS_HOME}:$CLASSPATH
eoc

Restart the domain using whatever wrappers you have configured. This is perhaps the most customized area of WebLogic administration ! The out of the box stopManagedWebLogic.sh, stopWebLogic.sh, startWebLogic.sh and startManagedWebLogic.sh in ${DOMAIN_HOME}/bin can be used too.

Testing in the WebLogic domain

Once the domain has started, point your browser to each one of the agents listening on http://localhost:600[0-3] and check the information they obtain from their respective server. Here is the administration server’s agent view:

Here is an exemple for the mbean Security_Name=myrealmDefaultIdentityAsserter running in the managed server IBR_server1’s JMX agent accessible here: http://localhost:6001/ViewObjectRes//Security%3AName%3DmyrealmDefaultIdentityAsserter.

This can be compared with the view from SimpleHTTPServer presented in the aforementioned article and accessible here for example:
http://localhost:10001/DomainServices/DomainRuntimeService/DomainConfiguration/webcenter/SecurityConfiguration/webcenter/DefaultRealm/myrealm/AuthenticationProviders/DefaultIdentityAsserter/Realm/myrealm/AuthenticationProviders/DefaultIdentityAsserter

We notice that clicking on a property of MBean pops up its description. Also, a list of the current MBean’s operations are displayed at the bottom and can be invoked, some are parameterless and some requires one or more parameters.
Referenced mbeans can be digged further by clicking on their value displayed in the rightmost column, e.g. for the Realm mbean :

Conclusion

The HtmlAdaptorServer agent presents a nice HTML interface to the run-time mbeans. Unlike a stand-alone tool such as jconsole, it requires to be installed in the servers to observe but this step is quite smooth. It is a tool aimed mostly at developers who need to interactively troubleshoot their mbeans in development where they can change some properties if needed.