java
Java-Monitor Forum » Installation Instructions
Installing the Java-monitor probe

To be able to use Java-monitor, you have to install a small probe in your application server.

The steps are as follows:

  1. Check prerequisites.
  2. Download the probe.
  3. Install the probe in your application server.
  4. Grab a coffee.
  5. Check the stats on Java-monitor.
  6. Set up SMS notifications.
We will detail each of these steps below.

1. Check Prerequisites

The Java-monitor probe needs Java version 1.5 or newer to run. The reason for this prerequisite is that the statistics that we are collecting simply are not available in older versions of Java.

The current probe is designed to run in a JEE application server, such as Tomcat, Jetty, JBoss, Glassfish or one of the many other application servers. You can even monitor plain Java applications if you like.

2. Download the Probe

Please register and log in:

User name: Password:

Once downloaded, unzip the probe. Java-monitor's probe comes as a WAR file, which you'll find in the zip you downloaded.

This WAR file is specific for your Java-monitor account. You can deploy it in as many application servers as you like. Each application server will show up separately on Java-monitor. You don't have to keep the probe around for later. You can download it at any time.

3. Install the Probe in your Application Server

The Java-monitor probe is a simple WAR file. It has no dependencies. If you are familiar with deploying WAR files, you can simply use your normal procedure and ignore the advice below.

  • For Tomcat, unzip the downloaded file and copy java-monitor.war into the ${CATALINA_BASE}/webapps/ folder.
  • For JBoss, unzip the downloaded file and copy java-monitor.war into the ${JBOSS_HOME}/server/default/deploy/ folder.
  • For Glassfish, unzip the downloaded file and copy java-monitor.war into the ${GLASSFISH}/domains/domain1/autodeploy/ folder.
  • For SpringSource dm Server, unzip the downloaded file and copy java-monitor.war into the ${SERVER_HOME}/pickup/ folder.
  • For OC4J Standalone use the Enterprise Manager web interface.

For all other JEE application servers simply use the procedure as discussed in your server's documentation.

If you use Jive Software's Openfire XMPP server, open the administrative console and install java-monitor-plugin.jar. Navigate to the plugins tab and choose "upload plugin". For Openfire, you do not need java-monitor.war and you can safely ignore it.

4. Grab a Coffee

At this point, you'll have to wait a little while. The Java-monitor probe pushes data every minute. It will be a few minutes before the graphs on Java-monitor are useful or even interesting.

Why don't you make yourself a cup of coffee and sit back a bit. After all, you have just set up monitoring in a matter of minutes and saved your employer hours of work.

Here is some reading to keep you entertained.

Light Reading: Java-monitor Architecture

Java-monitor is a centralised monitoring system for Java applications. Just as Google offers centralised mail services, we offer centralised monitoring services.

You installed a probe in the JVM of your application server. The probe serves to send statistics to Java-monitor. You can view these statistics from your web browser. The image below shows this process.

architecture overview

On the left is your application server, running on a Java virtual machine. You have just installed the Java-monitor probe in that server and it is transmitting statistics as you read this.

The server stores the statistics. If you return to the Java-monitor forum, you'll see these statistics and monitor your servers.

Light Reading: Security Considerations

Java-monitor does not have access to your application servers. There is no way for Java-monitor to even contact your application server. It may be running in-house, behind a firewall and maybe even NAT. Instead, the probe periodically contacts the Java-monitor collector service to push data out to Java-monitor. There are no facilities for the Java-monitor server to give commands to the probe. All it does is receive data.

If you prefer to convince yourself, the complete source code of the Java-monitor probe is included in the probe's WAR file. It is also available as the java-monitor probes Google code project. You can download the code there to review it. You can even to build your own custom probe if you like.

You are the only one who can see the data that flows to the Java-monitor server. None of the other members has access to your statistics or your graphs. If you like, you can choose to publish snapshots of graphs on the forum. Publishing a snapshot only shows the data as you see it on the screen. No other graphs or data is published unless you explicitly order Java-monitor to do so.

Actually, that is not completely true. You can invite other Java-monitor users to be your friend on the forum. Users that you have marked as friends can view your host statistics also. Unless you switch that off for a particular host, of course. This can be useful if you are on the road for a few days and you'd like to have someone watchone of your machines for you.

All measurement data expires after 2 days. If you remove java-monitor.war from your application servers and wait for two days, your statistics data is automatically deleted. 30 days later even the host's records on your account are deleted and only your account remains.

Each probe contains a limited key that gives it just enough access to push data into your account. This key is not enough to log into the forum or access your graphs and statistics. Please keep this key, and thus the probe, private.

5. Check the Stats on Java-monitor

Well, with your coffee finished, there should be something to look at on Java-monitor. The panel below should now show your monitored hosts. Alternately, go back to the forum and check out the server's statistics.

6. Set up SMS notifications

Your servers are now being monitored. Java-monitor will send you an e-mail notification if a server stops sending data for more than 2 minutes. If you would like to receive these messages when you are on the road, you can configure a host to send its notification via SMS.

You can enter your telephone number in the forum's user control panel. To specify which hosts should alert you via SMS, just open the details page of the host. In the host configuration block you can enable SMS messages for that host.

If you have any questions about where your SMS credit went, or how many messages have been sent, you can see an SMS credit report in the forum's user control panel.

Common Problems and Solutions: Same JVMs Keep Showing Up As Different Host

If you are running in highly dynamic environments like for instance Amazon's EC2, you may find that your JVM's keep coming back as 'new' every time. Over time, you end up with a large number of JVM lines in your host overview, most of them inactive. The problem is that Java-monitor relies on (among other things) the local IP address of the host to identify each JVM. If the local IP address changes a lot, Java-monitor thinks it is dealing with a new JVM every time.

To resolve this, you can override the built-in JVM identification by giving your JVM a unique ID. Add the following system property to the command line:


        ... -Djavamonitor.uniqueid=12 ...

For '12', fill in a number you like or that is meaningful to you. You are free to pick any number, as long as you choose a different one for each JVM that you run on a physical or virtual host.

For example, for a Tomcat server on a UNIX machine you can use:


        % JAVA_OPTS="${JAVA_OPTS} -Djavamonitor.uniqueid=12"
        % export JAVA_OPTS
        % bin/startup.sh

Java-monitor.com works without writing anything to your JVM or the machine that hosts it. We do this for security reasons (we don't even want write access to your server), but it restricts our ability to identify individual JVMs. We urge you to only set the unique ID in case you have problems. If everything works well without this configuration that is much easier for you to manage.

Common Problems and Solutions: HTTP Proxies

Java-monitor sends data out to the Java-monitor collector servers via HTTP. If your application server cannot make a direct connection, but has to use an HTTP proxy, you have to configure your JVM to do so. For example, to use a proxy named "proxy.example.com" on port 8080, add the following options to your VM arguments.


        java -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 ...

For a Tomcat server on a UNIX machine you can use:


        % JAVA_OPTS="${JAVA_OPTS} -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080"
        % export JAVA_OPTS
        % bin/startup.sh

For proxies that require authentication, you can use -Dhttp.proxyUser and -Dhttp.proxyPassword. For example:


        % JAVA_OPTS="${JAVA_OPTS} -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 
			-Dhttp.proxyUser=kjkoster -Dhttp.proxyPassword=secret"
        % export JAVA_OPTS
        % bin/startup.sh

Common Problems and Solutions: Java Security Managers

Java has an integrated security manager, which may have been enabled by your packager. In some cases, the security manager may block the Java-monitor probe from working. If that is the case, you will find exceptions such as the one below in your server's log files.


        java.security.AccessControlException: access denied (java.util.PropertyPermission javamonitor.uniqueid read)
                at java.security.AccessControlContext.checkPermission (Unknown Source)
                at java.security.AccessController.checkPermission(Unknown Source)
                at java.lang.SecurityManager.checkPermission(Unknown Source)
                at java.lang.SecurityManager.checkPropertyAccess(Unknown Source)
                at java.lang.System.getProperty(Unknown Source)
                at com.javamonitor.JavaMonitorCollector.(JavaMonitorCollector.java:63)
                ...

In order to solve this, grant the Java-monitor probe access to your JVM's internals. Without such access, the probe cannot collect data from your JVM and Java-monitor cannot monitor your server.

Locate your security policy file and add the following lines to it:


        grant codeBase "file:${catalina.base}/webapps/java-monitor/-" {
                permission java.security.AllPermission;
        };

Please notice that some repackaged Tomcat servers enable the security manager by default. This is the case for example on Debian and Ubuntu Linux systems if you installed the apt-package for Tomcat instead of downloading a normal Tomcat from Apache.org.

To learn more about Java's security manager, check out Tomcat's Security Manager Howto, and Sun's documentation on Java policy files.