JETM Web Integration

JETM offers some basic web integration capabilities. The following page contains a step-by-step guide to enable JETM performance monitoring in a web application. If you are using the Spring Framework please see Spring Framework Integration.

Step 1: Attach JETM to web application lifecycle

First of all the JETM runtime has to be started. Therefore we attach JETM to the web application lifecycle using a ServletContextListener. The EtmMonitorContextListener is a ServletContextListener implementation that starts and stops JETM at web application start and stop. It will use the EtmMonitor described in a file called jetm-config.xml that should be part of the web application classpath.

In order to integrate JETM to your web application add the following listener configuration to your web.xml and create a new file called jetm-config.xml that contains the second XML code fragment.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
         xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                             http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
  <listener>
    <listener-class>etm.contrib.integration.web.EtmMonitorContextListener</listener-class>
  </listener>
<web-app> 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jetm-config PUBLIC "-// void.fm //DTD JETM Config 1.2//EN"
                             "http://jetm.void.fm/dtd/jetm_config_1_2.dtd">
<jetm-config type="nested">

</jetm-config>

Step 2: Access aggregated results

As described in JETM drop-in HTTP Console aggregated performance results can be accessed through a dedicated servlet called HttpConsoleServlet. The following web.xml fragment provides access to performance results at http://{HOST}:{PORT}/{ROOT}/performance/:

  ...

  <servlet>
    <servlet-name>performanceMonitor</servlet-name>
    <servlet-class>etm.contrib.integration.web.HttpConsoleServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  ...

  <servlet-mapping>
    <servlet-name>performanceMonitor</servlet-name>
    <url-pattern>/performance/*</url-pattern>
  </servlet-mapping>

Step 3: Monitor HTTP or SOAP Requests

For high level performance monitoring JETM includes two HTTP servlet filters that may be used to record execution times of HTTP or SOAP requests. The class HttpRequestPerformanceFilter will record HTTP GET and POST requests and use the request uri as name; the class SoapActionPerformanceFilter can be used to record document/literal SOAP requests that provide a "SOAPAction" HTTP Header.

The following web.xml excerpt enables SOAPAction based monitoring for a web service endpoint at /services/*.

  ...
  
  <filter>
    <filter-name>performance-monitor</filter-name>
    <filter-class>etm.contrib.integration.web.SoapActionPerformanceFilter</filter-class>
  </filter>
      
  <filter-mapping>
    <filter-name>performance-monitor</filter-name>
    <url-pattern>/services/*</url-pattern>
  </filter-mapping>

Step 4: Customize web integration

If you want to customize the configuration in Steps I to Step III the following options exists:

Customize JETM configuration file location

It is possible to override the name of the file using the web application context parameter jetm.config.filename. Example:

<context-param>
  <param-name>jetm.config.filename</param-name>
  <param-value>custom-config.xml</param-value>
</context-param>

As an alternative the jetm config file may be loaded from file system. This feature can be enabled by specifying jetm.config.filepath as context parameter. In the example below the jetm config file is expected at /etc/yourapp under the name supplied with jetm.config.filename. If jetm.config.filename is unset, the default name jetm-config.xml will be used.

<context-param>
  <param-name>jetm.config.filepath</param-name>
  <param-value>/etc/yourapp</param-value>
</context-param>

While this feature sounds convenient a hard coded filepath within a web.xml descriptor is often considered a design or programming error. Therefore the path to a jetm config file can be specified using a system property. Just write jetm.config.filepath as ant style property and its value will be retrieved from System#getProperty(String) using the given name. Example:

<context-param>
  <param-name>jetm.config.filepath</param-name>
  <param-value>${myapp.jetm.path}</param-value>
</context-param>