Advanced documentation of Java Melody

For standard documentation, see UserGuide

Table of contents

• Setup JavaMelody in an ear file
• 1. Jar files
• 2. web.xml file
• 3. First results
• 4 to 17. Other settings (optional parameters, JDBC, EJB3, etc)
• Optional centralization server setup
• 1. War file of the webapp of monitoring
• 2. Deployment of the webapp of monitoring
• 3. Simpler alternative of deployment of the webapp of monitoring
• 4. Results with a collect server
• 5. Security with a collect server
• Business facades (without EJB3 and without Spring and without Guice)
• Alternative for monitoring of sql requests
• Monitoring of sql requests and of jdbc connections in GlassFish v3+
• Usage of JavaMelody in JBoss AS 7 (which uses OSGI)
• Usage of JavaMelody in JonAS 5 (which uses OSGI)
• Deployment on Tomcat without modification of monitored webapps (beta)
• Debugging logs
• Clearing all statistics and all graphs
• Customizing styles, icons and other resources in the html reports
• Report written before last shutdown
• Format of RRD files
• Compilation and development

Setup JavaMelody in an ear file

(Written based on a contribution by 'dhartford')

If you deploy your application with a war file or with an equivalent directory, just follow the UserGuide.

If you deploy your application with an ear file, probably because you use EJBs, this chapter will guide you to setup JavaMelody in your ear.

Note that if you have class loading issues with an ear, the use of a single war instead of an ear could help (and with JavaEE 6, you can even use EJBs in a single war).

1. Jar files

Copy the files javamelody.jar and jrobin-x.jar, located at the root of the supplied javamelody.zip file, to the lib directory of the ear of the application to monitor (lib directory is "required" by the JavaEE 5 specification). If you want to have reports in PDF format or weekly reports by mail, copy also the itext-x.jar file to the same location.

To declare the jar files in the ear, modify the /META-INF/application.xml file in your ear like this:

	<application version="5"
		xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd">
		....
		<module>
			<java>lib/javamelody.jar</java>
		</module>
		<module>
			<java>lib/jrobin-x.jar</java>
		</module>
		<module>
			<java>lib/itext-x.jar</java>
		</module>
		<module>
			<web>
				<web-uri>mywebapp.war</web-uri>
				<context-root>mycontext</context-root>
			</web>
		</module>
		....
	</application>

If you use Maven, you may want to use the maven ear plugin and the includeInApplicationXml flag to make this file.

2. web.xml file

You need to have the war of a single monitored webapp in your ear. If you do not have a war, create it with a simple web.xml file in the WEB-INF directory of the war. And modify the web.xml file of this war like written in chapter "web.xml file" of the UserGuide.

3. First results

You can now view the monitoring: deploy your ear and open the following page in a web navigator after starting the server:

http://<host>/<context>/monitoring

where <host> is the name of the server where the application is deployed, followed possibly by the port (for example localhost:8080) and where <context> is the name of the context of the webapp which you have configured in the ear.

Then you can complete the settings as below according to your needs.

4 to 17. Other settings (optional parameters, JDBC, EJB3, etc)

To complete the settings, just follow chapters 4 to 17 of the UserGuide. As you use an ear file, you may be interested by the chapter "Business façades (ejb-jar.xml file if EJB3)" for example.

Optional centralization server setup

A centralized collect server can be used optionally. This server can centralize in a same user interface and with a unique storage the monitoring of several applications (QA and production for example) and / or the monitoring of an application with several instances of servers (a cluster for example). So the reports, the storage and the charts are moved out of the monitored application to the collect server.

Please note that the centralized collect server with javamelody.war only works if the monitoring already works with javamelody.jar in the target application at http://<host>:<port>/<context>/monitoring. An application must not be monitored from two collector servers.

1. War file of the webapp of monitoring

Copy the javamelody.war file, located at the root of the supplied javamelody.zip file, to the centralized server. The javamelody.war file should be in general of the same version of monitoring as the version of the javamelody.jar file in the monitored application.

2. Deployment of the webapp of monitoring

Note : An alternative which does not need an application server is described in the following chapter.

Deploy the javamelody.war file in the application server of the centralized server. If it is Tomcat, you can write an xml context file named 'javamelody.xml' in the directory conf/Catalina/localhost of Tomcat as in the following example:

	<?xml version="1.0" encoding="UTF-8" ?>
	<Context docBase="<pathto>/javamelody.war" path="javamelody" reloadable="false" >
		<Parameter name='javamelody.resolution-seconds' value='120' override='false'/>
	</Context>

The optional parameters resolution-seconds, storage-directory, system-actions-enabled, warning-threshold-millis, severe-threshold-millis and allowed-addr-pattern can be added in the xml context file of the collect server with the prefix javamelody. They can also be added as system properties with the prefix javamelody.

They have the same effects on the collect server than those of a monitored application as written in the UserGuide. In particular the parameter resolution-seconds defines the period of calls to urls of applications from collect server and the resolution of charts in the monitoring. The parameter system-actions-enabled needs to be added with the value "true" both in the collect server and in the monitored applications.

The collect server can send weekly, daily or monthly reports by mail for each monitored application. For this, use in the collect server (in Tomcat context for example) exactly the same mail session, the same parameters and the same jar files as those in Weekly, daily or monthly reports by mail.

If xml format is desired instead of java serialization as transport format between a collect server and monitored applications, a parameter transport-format which is specific to the collect server can be added with 'xml' for value. The java serialization is the transport format by default and it is recommended for best performances (75% more performance for response time, according to this benchmark). The xml transport format needs a dependency on libraries xstream (BSD) and xpp3 (Public Domain) in the monitored webapps.

3. Simpler alternative of deployment of the webapp of monitoring

As an alternative to the deployment described in the last chapter for the webapp of monitoring in a java application server, it is possible to launch the winstone (LGPL) servlet container already included in the javamelody.war file. You only need to use the launch command "java -jar javamelody.war" and to specify in system properties each of the monitoring parameters detailed above.

Examples:

	java -jar javamelody.war
	java -Djavamelody.resolution-seconds=120 -jar javamelody.war

The settings of http ports, server mode, memory and logs can be done like this:

	java -server -Xmx128m -jar javamelody.war --httpPort=8080 --ajp13Port=8009 2>&1 >>javamelody.log

Other parameters exist for the servlet container. You can read them with:

	java -jar javamelody.war --usage

On Linux and Unix, it is possible to launch this server as a daemon (in background) and with logs like this (wikipedia):

	nohup java -server -jar javamelody.war 0</dev/null 2>&1 >>javamelody.log &

4. Results with a collect server

To view the monitoring: open the following page in a web navigator after starting the servers:

http://<host>/javamelody

where <host> is the name of the collect server, followed possibly by the port (for example localhost:8080) and where 'javamelody' is the name of the context of the webapp as the name of the 'javamelody.xml' file.

With links by application in reports, you can choose the application that you want to monitor.

In the web page, you can add an application to monitor and its access url (for example "http://<host_qa>/myapp/" for "qa" and "http://<host_production>/myapp/" for "production"). If an application to monitor is deployed on several instances of servers (in a cluster or in a farm), urls should be separated by ',' (for example "http://<host1>/myapp/,http://<host2>/myapp/" for "cluster"). Of course, you can otherwise add each instance individually. Note: it is not possible to monitor one application in several collect servers or twice in one collect server.

In order for the collect server to monitor an application, the monitoring should be setup in this application as written at the start of this chapter. When the monitoring is setup in the application, it is not compulsory to include the jrobin-*.jar file in the WEB-INF/lib directory of the application, as only the collect server will handle the charts for this application.

5. Security with a collect server

And with this setup again, it is possible to restrict access to the monitoring of the application only to the collect server by its ip address, forbidding access to the monitoring of the application to any others. For example, if the monitored application is on the same server as the collect server, the following parameter can be added in the web.xml file of the monitored application to restrict access and to allow only the local collect server:

	<init-param>
		<param-name>allowed-addr-pattern</param-name>
		<param-value>127\.0\.0\.1</param-value>
	</init-param>

If the monitored application is a Hudson, Jenkins, JIRA, Confluence or Bamboo server, the system property -Djavamelody.plugin-authentication-disabled=true can be added to the monitored server in order to disable authentication of the monitoring page in the javamelody plugin and to be able to add the server to a centralized collect server. (A system property like -Djavamelody.allowed-addr-pattern=127\.0\.0\.1 can also be added with the ip address of the collect server.)

Furthermore, if you do not want the people having access to the collect server to be able to add or remove applications to monitor, you can forbid the writing to the file "applications.properties" which contains the list of the applications to monitor. This file is located in the storage directory, "temp/javamelody/applications.properties" for example. The user of the OS running the java process of the collect server must be allowed to read the file but without being allowed to write it. Only you, by using "root" for example, will be able by editing the file to add or to remove applications as the collect server would do. And in this case, the links "add an application" and "remove an application" will not be displayed in the collect server.

See also the comment by Chris at the bottom of this page.

Business facades (without EJB3 and without Spring and without Guice)

If the application to monitor contains some business façades with Java interfaces, a counter can be created for statistics of execution of methods on these façades even if these interfaces are neither EJB3 nor Spring nor Guice.

First, if these façades are EJB3, Spring or Guice, then it is simpler to use the configuration described in the user guide. Otherwise let's say that a business façade has an interface with an implementation, which is instanciated in a factory for example as below:

        public interface MyFacade { ... }
        
        public class MyFacadeImpl implements MyFacade { ... }

        public class Factory {
                public static MyFacade createMyFacade() {
                        final MyFacade myFacade = new MyFacadeImpl();
                        return myFacade;
                }
        }

So it is a standard Java interface (ie POJI or Plain Old Java Interface). Then you just need to modify the code of the instanciation like this:

        public class Factory {
                public static MyFacade createMyFacade() {
                        final MyFacade myFacade = net.bull.javamelody.MonitoringProxy.createProxy(new MyFacadeImpl());
                        return myFacade;
                }
        }

As pre-requisites for this, the jar of javamelody must be available in the classpath used to compile sources and façades must have interfaces and not only implementations.

If the name displayed by the monitoring for the class does not please you, you can name the proxy like this:

	public class Factory {
		public static MyFacade createMyFacade() {
			final MyFacade myFacade = net.bull.javamelody.MonitoringProxy.createProxy(new MyFacadeImpl(), "my business use case");
			return myFacade;
		}
	}

Alternative for monitoring of sql requests

If for any reason you can't monitor sql requests with a jdbc datasource or with a jdbc driver as said in the JDBC chapter of the user guide, and if you use Hibernate then there is an alternative for monitoring of sql requests: define the Hibernate property "hibernate.jdbc.factory_class" with the value "net.bull.javamelody.HibernateBatcherFactory". It will enable the display of statistics of sql requests and the display of active jdbc connections.

For example, if you use an "hibernate.cfg.xml" file, add the following with the other Hibernate properties:

	<property name="hibernate.jdbc.factory_class">net.bull.javamelody.HibernateBatcherFactory</property>

Monitoring of sql requests and of jdbc connections in GlassFish v3+

If you use a JDBC DataSource from JNDI with GlassFish v3 or more, the SQL requests and the JDBC connections are probably not monitored.

To monitor them, it is needed to do the following, for each JDBC DataSource:

• It is supposed that the DataSource is for example currently named "jdbc/MyDataSource" in GlassFish
• Download javamelody-objectfactory.jar and copy this file in the lib directory of your GlassFish server
• In the GlassFish admin console, rename your JDBC Resource (DataSource) from "jdbc/MyDataSource" to "jdbc/MyDataSource_uncached" for example
• Also in the GlassFish admin console, create a JNDI custom resource like this:

or use the following asadmin command

asadmin create-custom-resource --restype javax.naming.spi.ObjectFactory --factoryclass javamelody.CachedObjectFactory --property jndi-ref=jdbc/MyDataSource_uncached jdbc/MyDataSource

or you can use the asadmin add-resources /path/to/sample-resource.xml command with the file sample-resource.xml

• Then in the details of the resource in the GlassFish admin console, define the target of the custom resource if the monitored webapp is deployed on another target instance than the Admin Server
• Test: Webapp uses "jdbc/MyDataSource" as before to lookup from JNDI (and now it is the custom resource referencing "jdbc/MyDataSource_uncached"). After some usage of the webapp, the statistics of the SQL requests should be displayed in the monitoring report.

This should work with every versions of JavaMelody since v1.23.

Usage of JavaMelody in JBoss AS 7 (which uses OSGI)

JBoss AS 7 uses OSGI and so you need to add a configuration in JBoss to use JavaMelody.

Add com/sun/management to jboss-as-7/modules/sun/jdk/main/modules.xml:

    ...
    <dependencies>
        <module name="system" export="false" services="import">
            <exports>
                <include-set>
                    <path name="com/sun/management"/>
                    <path name="com/sun/script/javascript"/>

Otherwise you will have a java.lang.NoClassDefFoundError: com/sun/management/OperatingSystemMXBean

Usage of JavaMelody in JonAS 5 (which uses OSGI)

JonAS 5 uses OSGI and so you need to add a configuration of felix in JonAS to use JavaMelody.

Copy the content of the latest felix-config.properties for JonAS in a file named "felix-config.properties" and written in the "conf" directory of your JonAS server. If the content of this latest file does not suit your JonAS version, you can find the "felix-config.properties" file for your version in the felix jar file of your server.

In your "felix-config.properties" file, add the following system packages after the existing "org.osgi.framework.system.packages" declaration:

"com.sun.management" and "sun.nio.ch".

For example:

org.osgi.framework.system.packages com.sun.management; \
				   sun.nio.ch; \
				   org.osgi.framework; version=1.5.0, \

Then add a system property in your launch file: -Djonas.felix.configuration.file=$JONAS_BASE/conf/felix-config.properties

Deployment on Tomcat without modification of monitored webapps (beta)

If there is one or several webapp(s) to monitor which are deployed on Tomcat 6, it is possible to monitor this or these webapp(s) without modification of this or these webapp(s), (except that it may not work well from javamelody v1.32 up to v1.35). That is to say without modification of the war file or of the directory of these webapps.

For this, copy the files javamelody.jar and jrobin-x.jar and optionally itext-x.jar in the lib directory of Tomcat 6 (and not in the WEB-INF/lib directories of the webapps).

Then add the following lines in the web.xml file of the conf directory of Tomcat (and not in the WEB-INF/web.xml files of the webapps).

	<filter>
		<filter-name>monitoring</filter-name>
		<filter-class>net.bull.javamelody.MonitoringFilter</filter-class>
	</filter>
	<filter-mapping>
		<filter-name>monitoring</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>
	<listener>
		<listener-class>net.bull.javamelody.SessionListener</listener-class>
	</listener>

In this conf/web.xml file of tomcat, some parameters can be added as written in the user guide.

So and without modification of the webapps, all webapps deployed in this Tomcat instance are monitored (and it is then not possible to choose which, otherwise than with the url-exclude-pattern parameter described in the user guide). This technique is specific to Tomcat 6 and does not apply to other JavaEE implementations.

The ClassLoader in application servers is a complex subject. In consequence :

• This feature is considered as beta for now

• It works only in Tomcat 6 (Tomcat 5.5 is not supported)

• It does not seem advisable to use the monitoring by Spring AOP in this case

Debugging logs

Logs for debugging are available using either logback if found, or log4j if found or java.util.logging otherwise. The log messages for debugging are written using the category "net.bull.javamelody" and the level "debug".

Moreover, some stack-traces of unusual exceptions are logged using logback or log4j or java.util.logging, in the same category with the level "info" or "warn".

If the logback library is available in your monitored webapp, you can display debugging logs by adding or modifying the "logback.xml" file in your "WEB-INF/classes" directory. For example:

	<?xml version="1.0" encoding="UTF-8" ?>
	<configuration>
		<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
			<encoder>
				<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
				</pattern>
			</encoder>
		</appender>
	
		<!-- http requests log -->
		<logger name="javamelody">
			<level value="info" />
		</logger>
		
		<!-- debugging log -->
		<logger name="net.bull.javamelody">
			<level value="debug" />
		</logger>
	
		<root level="debug">
			<appender-ref ref="STDOUT" />
		</root>
	</configuration>

Or if the log4j library is available in your monitored webapp, you can display debugging logs by adding or modifying the "log4j.xml" file in your "WEB-INF/classes" directory. For example:

	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
	<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">
		<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
			<param name="Threshold" value="DEBUG" />
			<layout class="org.apache.log4j.PatternLayout">
				<param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c] %m%n" />
			</layout>
		</appender>
	
		<!-- http requests log  -->
		<category name="javamelody">
			<priority value="info" />
		</category>
		
		<!-- debugging log -->
		<category name="net.bull.javamelody">
			<priority value="debug" />
		</category>
		
		<root>
			<appender-ref ref="CONSOLE" />
		</root>
	</log4j:configuration>

Here is an example of debugging logs:

11:11:00.120 [main] DEBUG net.bull.javamelody - JavaMelody listener init started
11:11:00.151 [main] DEBUG net.bull.javamelody - datasources found in JNDI: [java:comp/env/jdbc/TestDB2, java:comp/env/jdbc/TestDB]
11:11:00.167 [main] DEBUG net.bull.javamelody - datasource rebinded: java:comp/env/jdbc/TestDB2 from class org.apache.tomcat.dbcp.dbcp.BasicDataSource to class $Proxy0
11:11:00.167 [main] DEBUG net.bull.javamelody - datasource rebinded: java:comp/env/jdbc/TestDB from class org.apache.tomcat.dbcp.dbcp.BasicDataSource to class $Proxy0
11:11:00.167 [main] DEBUG net.bull.javamelody - JavaMelody listener init done
11:11:00.182 [main] DEBUG net.bull.javamelody - JavaMelody filter init started
11:11:00.182 [main] DEBUG net.bull.javamelody - OS: Windows XP Service Pack 3, x86/32
11:11:00.182 [main] DEBUG net.bull.javamelody - Java: Java(TM) SE Runtime Environment, 1.6.0_21-b06
11:11:00.182 [main] DEBUG net.bull.javamelody - Server: Apache Tomcat/6.0.26
11:11:00.182 [main] DEBUG net.bull.javamelody - Webapp context: /test
11:11:00.182 [main] DEBUG net.bull.javamelody - JavaMelody version: 1.19.0-SNAPSHOT
11:11:00.182 [main] DEBUG net.bull.javamelody - Host: xxx@xxx
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: resolution-seconds=60
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: log=true
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: system-actions-enabled=true
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: mail-session=mail/Session
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: admin-emails=xxx
11:11:00.182 [main] DEBUG net.bull.javamelody - parameter defined: mail-periods=day,week,month
11:11:00.292 [main] DEBUG net.bull.javamelody - log listeners initialized
11:11:00.307 [main] DEBUG net.bull.javamelody - datasources found in JNDI: [java:comp/env/jdbc/TestDB2, java:comp/env/jdbc/TestDB]
11:11:00,386 INFO  [org.quartz.simpl.SimpleThreadPool] Job execution threads will use class loader of thread: main
11:11:00,432 INFO  [org.quartz.core.QuartzScheduler] Quartz Scheduler v.1.5.2 created.
11:11:00,432 INFO  [org.quartz.simpl.RAMJobStore] RAMJobStore initialized.
11:11:00,432 INFO  [org.quartz.impl.StdSchedulerFactory] Quartz scheduler 'DefaultQuartzScheduler' initialized from default resource file in Quartz package: 'quartz.properties'
11:11:00,432 INFO  [org.quartz.impl.StdSchedulerFactory] Quartz scheduler version: 1.5.2
11:11:00.432 [main] DEBUG net.bull.javamelody - job global listener initialized
11:11:00.432 [main] DEBUG net.bull.javamelody - counters initialized
11:11:00.495 [main] DEBUG net.bull.javamelody - counters data read from files in xxx\apache-tomcat-6.0.26\temp\javamelody\test_xxx
11:11:00.511 [main] DEBUG net.bull.javamelody - collect task scheduled every 60s
11:11:00.776 [main] DEBUG net.bull.javamelody - first collect of data done
11:11:00.792 [main] DEBUG net.bull.javamelody - mail report for the day period scheduled with next execution date at Wed Aug 18 00:00:00 CEST 2010
11:11:00.792 [main] DEBUG net.bull.javamelody - mail report for the week period scheduled with next execution date at Sun Aug 22 00:00:00 CEST 2010
11:11:00.792 [main] DEBUG net.bull.javamelody - mail report for the month period scheduled with next execution date at Wed Sep 01 00:00:00 CEST 2010
11:11:00.792 [main] DEBUG net.bull.javamelody - mail reports scheduled for xxx
11:11:00.792 [main] DEBUG net.bull.javamelody - JavaMelody filter init done

Clearing all statistics and all graphs

The storage files of statistics and of graphs are stored in the temporary directory of the server, unless if you have defined the "storage-directory" parameter. And there is a sub directory for each application.

For example, with tomcat it is the directory <TOMCAT_HOME>/temp/javamelody/. With some other servers on linux, it is the directory /tmp/javamelody/. And for the Hudson / Jenkins plugin, it is the directory <HUDSON_HOME>/javamelody/.

To clear all statistics and all graphs:

• Stop the server

• Delete the storage directory : javamelody in the temporary directory of the server

• Restart the server. You can then open the report of the monitoring which is now empty.

But if you want to clear only the statistics, delete the *.gz files in the subdirectories of the storage directory. And if you want to clear only the graphs, delete the *.rrd files in the subdirectories of the storage directory.

Customizing styles, icons and other resources in the html reports

It can be helpful to customize styles, icons, effects and javascript or help files in the html reports (pdf reports excluded). The reports can be adapted to the styles of some enterprise applications with the CSS file. For example, add the following, before the monitoring filter, in the web.xml file of your webapp, in order to use your own css or icons:

 <filter>
	<filter-name>customResourceFilter</filter-name>
	<filter-class>net.bull.javamelody.CustomResourceFilter</filter-class>
	<init-param>
		<param-name>monitoring.css</param-name>
		<param-value>/customMonitoring.css</param-value>
	</init-param>
	<init-param>
		<param-name>bullets/green.png</param-name>
		<param-value>/static/bullets/red.png</param-value>
	</init-param>
 </filter>
 <filter-mapping>
	<filter-name>customResourceFilter</filter-name>
	<url-pattern>/monitoring</url-pattern>
 </filter-mapping>

Then add files "customMonitoring.css" and "static/bullets/red.png" at the root of the web content in your webapp. You can replace every web resource in this directory and its sub-directories: "src/main/resources/net/bull/javamelody/resource".

Report written before last shutdown

Sometimes a server is stopped in emergency or when there is a problem for example with the used memory. And perhaps, you did not thought of saving the JavaMelody report to have precise figures about the state of the server at this moment.

But don't worry, when the application is undeployed, JavaMelody writes a file called last_shutdown.html in the same storage directory as explained in the previous chapter. It is the JavaMelody report in html format, and it contains the statistics for the current day and the system information (such as the used memory) for the current time just before the application is undeployed, but it does not contain charts.

Format of RRD files

Values of charts are stored in RRD (Round Robin Database) format. Many tools exist for this format like RRDtool, close relative of MRTG, or JRobin in Java.

Compilation and development

See DevGuide