Documentation of JavaMelody

Table of contents

Introduction

The goal of JavaMelody is to monitor Java or Java EE application servers in QA and production environments.

It is not a tool to simulate requests from users, it is a tool to measure and calculate statistics on real operation of an application depending on the usage of the application by users. JavaMelody is mainly based on statistics of requests and on evolution charts.

It allows to improve applications in QA and production and helps to:

• give facts about the average response times and number of executions
• make decisions when trends are bad, before problems become too serious
• optimize based on the more limiting response times
• find the root causes of response times
• verify the real improvement after optimizations

Informations

• License: ASL since v1.50, LGPL before v1.50
• Java version required for execution: 1.6 or later (JDK or JRE or JRockit from Oracle or J9 from IBM)
• Server version required for execution: servlet api 2.4 at least (or JavaEE 1.4), like Tomcat 5.5 or +, GlassFish v2+, JBoss 4+, Jonas 4+, Jetty 6+, WebLogic 9+
• Required dependency: JRobin v1.5.9 (LGPL) for evolution charts
• Optional dependencies: iText v2.1.7 (MPL or LGPL) for reports in pdf format in addition to html.
• Languages: English, French, German, Portuguese and Chinese

Overhead

Some discussions on the monitoring overhead in production were archived for information.

JavaMelody Plugins

To monitor a Jenkins, JIRA, Confluence, Bamboo or Liferay server or a Grails application, all you need to do is install a plugin specifically made for that.

Jenkins Plugin

If you want to monitor a Jenkins server, you can install JavaMelody by pointing and clicking with aJenkins plugin.

For this, open Jenkins and click "Manage Jenkins", "Manage plugins", "Available" then check the plugin called "Monitoring" and click the "Install" button at the bottom of the page. Restart Jenkins after the installation of the plugin.

You can then open the report from the "Manage Jenkins" page or from the addresshttp://yourhost/monitoring. You can also open the report for the nodes from the addresshttp://yourhost/monitoring/nodes. That's it.

Atlassian JIRA, Confluence and Bamboo Plugin

If you want to monitor a JIRA, Confluence or a Bamboo server, you can install JavaMelody easily with a JIRA/Confluence/Bamboo plugin. For this, see the following page

Liferay Plugin

To monitor a Liferay server v6.1 or later, including SQL requests, you can install a Liferay plugin in just a minute.

Sonar Plugin

To monitor a Sonar server v3.1 or later, you can install a Sonar javamelody plugin:

• Download the latest Sonar plugin jar file from releases
• Copy the file into the "extensions/plugins" directory of your Sonar server
• Restart Sonar

You can browse the monitoring page at http://<host>:<port>/monitoring

For example, if the server is local: http://localhost:9000/monitoring

Known issues: There is currently no authentication to secure the access to the monitoring page. The SQL requests are not monitored. And pull requests are welcome.

Grails Plugin

If you want to monitor an application developed with Grails, you can install JavaMelody in just one command with a Grails plugin: JavaMelody Grails plugin.

grails install-plugin grails-melody

JavaMelody Setup

An important value of the monitoring is a very simple and fast installation process. And in general, integration in an application is done by the software provider without any intervention from the client.

This integration can be done in less than 10 minutes, by automatic discovery of environment: it only requires to copy 2 jar files and to add 10 lines in a xml file.

Then this integration can be completed later by configuration as needed.

If you deploy your application with a war file or with an equivalent directory, read the following chapters.

But if you deploy your application with an ear file, probably because you use EJBs, follow theAdvanced user's guide.

Please note that the javamelody.war file is not used in installation here. And the javamelody.war file is not needed in most use cases.

1. Jar files

Copy the files javamelody.jar and jrobin-x.jar, located at the root of the supplied javamelody.zip file, to the WEB-INF/lib directory of the war of the webapp to monitor.

Or if you use Maven, add the javamelody-core dependency in the pom.xml file of your webapp.

2. web.xml file

If your application server is compatible with Servlet API 3.0 (like tomcat 7, glassfish v3 or jboss 6), this paragraph is generally not needed, you can skip it and launch the server as in the next paragraph, except if you use a web.xml file without version="3.0". Otherwise add the following lines in the file WEB-INF/web.xml of the war of the webapp, before the description of your servlet :

<filter>
    <filter-name>javamelody</filter-name>
    <filter-class>net.bull.javamelody.MonitoringFilter</filter-class>
    <async-supported>true</async-supported>
</filter>
<filter-mapping>
    <filter-name>javamelody</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>ASYNC</dispatcher>
</filter-mapping>
<listener>
    <listener-class>net.bull.javamelody.SessionListener</listener-class>
</listener>

<async-supported>true</async-supported> and <dispatcher>ASYNC</dispatcher> are needed to support asynchronous requests with Servlet API 3.0.

3. First results

You can now view the monitoring: deploy the war 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 webapp 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 during the deployment thereof.

If the starting of the server does not work and if you have an error in the output of the server complaining about a "window server" (in particular if you use Mac OS X server), add the system property "-Djava.awt.headless=true" (in the java launch command or in the administration user interface of the server; or if you use tomcat, you can add "java.awt.headless=true" in the file $CATALINA_HOME/conf/catalina.properties). And restart the server.

Then you can complete the settings as below according to your needs. And before using it in production, you probably want to secure the monitoring page using your own means or see thesecurity chapter.

4. PDF report generation

To generate PDF reports as well as html reports, adding the library iText v2.1.7 is required (licenceMPL or LGPL, the iText jar file alone is enough, without the other dependencies like iText-rtf).

Copy the file itext-2.1.7.jar, located in the directory src/test/test-webapp/WEB-INF/lib/ of the supplied javamelody.zip file, to the WEB-INF/lib directory of the war of the webapp to monitor. Or if you use Maven, add the itext dependency in the pom.xml file of your webapp. The PDF link will be available at the top of the html report.

5. Supplements in web.xml

url-pattern in web.xml file above can be adapted in order not to monitor some urls, possibly with several mappings on the same filter.

For example, use the following filter-mappings and url-patterns to monitor only urls like/servlet1/* and /servlet2/* but not the others like /static/* :

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

Note that the url-patterns must "contain" the url /monitoring in order to have reports.

As an alternative, you can use a single /* url-pattern and a filter parameter with a regular expression can be added before </filter> in order to exclude some urls, for example:

<filter>
    <filter-name>javamelody</filter-name>
    <filter-class>net.bull.javamelody.MonitoringFilter</filter-class>

    <init-param>
        <param-name>url-exclude-pattern</param-name>
        <param-value>/static/.*</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>javamelody</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
    <listener-class>net.bull.javamelody.SessionListener</listener-class>
</listener>

6. Optional parameters

It is possible to configure some settings. These parameters can be defined in ascending order of priority:

• in initialisation parameters of the filter (web.xml file in the webapp), for example:

<filter>
    <filter-name>javamelody</filter-name>
    <filter-class>net.bull.javamelody.MonitoringFilter</filter-class>
    <init-param>
        <param-name>log</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>
...

• in context parameters of the webapp with prefix javamelody.

In the web.xml file in the webapp, for example:

<context-param>
    <param-name>javamelody.log</param-name>
    <param-value>true</param-value>
</context-param>
...

Or in the context xml file of Tomcat conf or in Glassfish, for example:

<?xml version="1.0" encoding="UTF-8" ?>
<Context docBase="path_to/mywebapp.war" path="mywebapp" reloadable="false" >
    <Parameter name='javamelody.log' value='true' override='false'/>
</Context>

• in system properties with prefix javamelody. (java launch command or administration user interface of the server or $CATALINA_HOME/conf/catalina.properties if tomcat), for example:

... -Djavamelody.log=true

The parameter url-exclude-pattern is a regular expression to exclude some urls from monitoring as written above.

The parameter http-transform-pattern is a regular expression to transform descriptions of http requests and to delete dynamic parts (identifiers of objects for example), in order to aggregate the statistics on these requests irrespective of dynamic parts. This parameter replaces any part of the URL that matches the regular expression with a "$". So setting http-transform-pattern to \d+means that the URLs "/get/entity/10" and "/get/entity/20" both have their digits matched by the regular expression, and are then aggregated into the URL "/get/entity/$". (You can use lookbehind regexp if necessary.) This also reduces the number of RRD files in the storage directory, as new ones are not created for every id.

Similarly, the parameter sql-transform-pattern is a regular expression to transform descriptions of sql requests (not binded identifiers for a "in" clause for example) in order to be able to aggregate on these requests.

And the parameters ejb-transform-pattern, spring-transform-pattern, guice-transform-pattern, error-transform-pattern, log-transform-pattern, job-transform-pattern, jsf-transform-pattern, struts-transform-pattern and jsp-transform-pattern can transform descriptions of ejb3 methods, of spring methods, of guice methods, of http system errors, of system error logs, of names of jobs, of jsf actions, of struts actions or of jsp pages (in order to aggregate by ejb components and not by ejb methods for example)

The parameter log can activate logs of http requests at the INFO level (false by default). The http request will be logged with the duration and the size of the response in the log category corresponding to the name of the filter set in web.xml file, using Logback or Log4J if present in your application, or using java.util.logging otherwise.

The parameter storage-directory is the name of the directory of storage (javamelody by default). If the name of the directory starts with '/' (or on Windows, with drive specifier followed by '\', or if its prefix is "\"), it is considered as an absolute path, otherwise it is considered as relative to the temporary directory (<temp> in TOMCAT_HOME for tomcat). If this parameter is changed later, it is recommended to rename the physical directory at the same time. When using Tomcat, you can use variable substitution with system properties in the context xml file or in the web.xml file of your webapp. For example, to set the storage directory relative to the Tomcat home, add the following in the context file of the webapp in Tomcat conf: <Parameter name='javamelody.storage-directory' value='${catalina.base}/javamelody' override='false'/>.

The parameter resolution-seconds is the resolution of charts in seconds (60 by default). A resolution between 60 and 600 is recommended (ie 1 to 10 minutes). If this parameter is decreased, stored *.rrd files should be deleted for the parameter to be taken into account.

The parameters warning-threshold-millis and severe-threshold-millis are the thresholds in milliseconds (global mean + 1 standard deviation and global mean + 2 x standard deviation by default, this default setting gives dynamic thresholds which indicate the requests with unusual mean times regardless of the application). Beyond the thresholds the mean times are displayed in orange or in red and are separately counted in summary tables with their average time percentages, hits, etc. These threshold parameters can serve as a basis for a SLA (service level) of an application, for which constraints can be defined such as "response time less than 2s for 90% of http requests".

The parameter displayed-counters can modify the displayed counters for the statistics and for the graphics (http,sql,error,log by default). So the counters displayed by default are those with keys http, sql, error and log. The counters with keys jsf, struts, jsp, ejb, spring, guice and services are automatically displayed when they are used (see below for ejb, spring, guice or struts and see the Advanced user's guide for services without ejb, spring and guice). So the parameterdisplayed-counters can hide some counters with for example the value http,sql,ejb,spring.

The parameter monitoring-path (/monitoring by default) is used to change the path in the URL to open the report of the monitoring. For example, http://.../admin/performance in place ofhttp://.../monitoring

The parameter system-actions-enabled (true by default) enables or disables the system actions garbage collector, http sessions, heap dump, memory histogram, process list, jndi tree, opened jdbc connections, database (near the bottom of reports). These actions have confirmations when necessary.

The parameter gzip-compression-disabled disables the compression of the monitoring reports, for example if there is another mechanism which would compress a second time (false by default, the reports are compressed by default if the browser supports it).

The parameter no-database just disables the monitoring of jdbc connections, the monitoring of sql requests and the reports on the database in system information. Set it to true to disable all that.

The parameter disabled (false by default) just disables the monitoring. This allows for example to disable the monitoring temporarily or only on some servers, from the tomcat context or from system properties without modifying the web.xml file neither the war file of the monitored webapp.

7. JDBC

If a DataSource, which JNDI name is like "jdbc/MyDataSource", is configured in the application server (xml context of the webapp in Tomcat for example), the sql requests will be automatically monitored without requiring any parameters (tested on Tomcat 5.5, 6 and 7, glassfish 3, jboss 5, weblogic 11g, jetty 6). Note that if JndiObjectFactoryBean is used for the DataSource in Spring, then SessionListener should be before ContextLoaderListener in the web.xml file or monitoring-spring.xml should be used as said below.

If a jdbc driver is used directly without DataSource, "net.bull.javamelody.JdbcDriver" should be defined as class of driver and the jdbc property "driver" should be added with the class of the real driver for value. For example, if you use a hibernate.cfg.xml file and mysql (without hibernate.connection.datasource):

<property name="hibernate.connection.driver_class">net.bull.javamelody.JdbcDriver</property>
<property name="hibernate.connection.driver">com.mysql.jdbc.Driver</property>
<property name="hibernate.connection.url">jdbc:mysql://localhost:3306/myschema</property>
<property name="hibernate.connection.username">myuser</property>
<property name="hibernate.connection.password">mypassword</property>

If a DataSource is used but its JNDI name is not like "jdbc/MyDataSource" or if this DataSource is not in one of the usual JNDI contexts "java:comp/env/" or "java:/", then you can add the optional parameter datasources (with a system property, a parameter of the context or of the filter) to define the JNDI name of the datasource used by the application. If there are several datasources, this parameter can contain the JNDI name of the datasources separated by commas. If a jonas v5 server is used, datasources can be monitored but it appears that the parameter datasources must be used to declare them.

For example, for a system property in server launch command:

-Djavamelody.datasources=java:comp/env/myapp/MyDataSource

If a DataSource is defined in a xml file of a Spring context, like for example <bean class="org.apache.commons.dbcp.BasicDataSource">...</bean> or <bean class="org.springframework.jndi.JndiObjectFactoryBean">...</bean>, the DataSource can also be monitored, with a Spring post-processor. Make sure the Spring configuration file (net/bull/javamelody/monitoring-spring.xml, included in the provided jar) is loaded as one of the first configuration files. For example, if you use theorg.springframework.web.context.ContextLoaderListener in your web.xml, thecontextConfigLocation context parameter will look something like this:

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>
    classpath:net/bull/javamelody/monitoring-spring.xml
    classpath:context/services.xml
    classpath:context/data-access-layer.xml
    /WEB-INF/applicationContext.xml
    </param-value>
</context-param>

If ever there is a conflict in your application between the all-in-one monitoring-spring.xml and AOP or @Autowired, then you can use the monitoring-spring-datasource.xml file, instead of monitoring-spring.xml. This file contains only the datasource post-processor and an example of SpringDataSourceFactoryBean.

8. Business facades (ejb-jar.xml file if EJB3)

If the application to monitor contains some business façades in EJB3 (Java EE 5) with annotations@Stateless, @Stateful or @MessageDriven, a counter can be created for statistics of execution of methods. But it is not recommended for response time to monitor execution of all the methods of EJB3 beans, for example the methods of low granularity as getters of entities.

相關推薦