Request Mapper Plug-in for Custom Requests

Content

One of the primary features of ITCAM for Application Diagnostics and ITCAM for WebSphere is the ability to monitor the response time of J2EE applications. Typical J2EE applications consist of servlets or JSPs for presentation; Enterprise Java Beans (EJBs) for business logic, and connectors and adapters to databases and other data sources. ITCAM AD dynamically instruments the J2EE classes to measure the amount of time taken in each component. These metrics are sent to the Managing Server and/or ITM monitoring agents for visualization, analysis and storage. With this information, individual transaction edge response time can be decomposed to show response times of the J2EE nested requests the transaction made. Furthermore, the nested request data includes context information about the request: a JDBC nested request shows the datasource name and SQL executed; an MQI call shows the Queue Manager and Queue name; a CTG call shows the Gateway and CICS applid.

However, some enterprise applications may not exclusively use J2EE-compliant services. There may be third-party vendor packages; open source software or home-grown APIs to supplement the application. These non-standard services can be monitored by defining Custom Request to the ITCAM Data Collector (DC). Customers can create Custom Request definitions to monitor edge or nested requests. The Custom Request definition specifies a Java class and method to instrument that encapsulates the request. The instrumentation adds byte code to the beginning of the method to identify the start of the request, and at the end of the method to identify the completion of the request. The time taken between these two instrumentation points is the request response time. Note that only a single method can be used to represent a request. For example, an API class that uses a method called ‘send()’ to start a request, and a method called ‘receive()’ to complete the request, cannot be instrumented as a custom request. Instead, look for a single method that wraps the send() and receive().

Custom request definitions are very useful. They provide additional insight into the components of response time. A custom request is usually defined in a user-created XML file in the ITCAM runtime, for example
/u/itcam71/runtime/custom_request.xml (although it can be on any filesystem accessible to the data collector). The name of the custom XML file is defined in file toolkit_custom.properties in the server runtime custom directory.



Using Apache Jakarta HTTP client as an example, a custom request could be defined as:

<customEdgeRequests>
<edgeRequest>
<requestName>HttpClient</requestName> <Matches>org.apache.http.impl.client.DefaultRequestDirector</Matches>
<type>application</type>
<methodName>execute</methodName>
</edgeRequest>
</customEdgeRequests>


There are limitations however. A custom request event displayed in the ITCAM VE consists only of the Custom Request name (assigned in the definition), and the class name of the custom request. It provides no context for the request. In our HTTP API example, it would be really useful to know what the destination URL for the request is, which is passed in a parameter to the HTTP API call. This is what a Custom Request Mapper is for.

Note: The Custom Request Mapper feature should not be confused with the HTTP Request Mapper. The HTTP Request Mapper is designed to assign alternate names to Servlet or JSP requests. The Custom Request Mapper is used to retrieve context data for user-defined Custom Requests.

A Custom Request Mapper is a simple customer-supplied Java class that will be invoked by the Custom Request method callback. The mapper program is specified as a sub-element of the <edgeRequest> tag, so that our custom request definition now reads:

<customEdgeRequests>
<edgeRequest>
<requestName>HttpClient</requestName> <Matches>org.apache.http.impl.client.DefaultRequestDirector</Matches>
<type>application</type>
<methodName>execute</methodName>
<customMapper>com.company.HttpClientMapper</customMapper>
</edgeRequest>
</customEdgeRequests>


The Mapper class must implement interface

com.ibm.tivoli.itcam.toolkit.ai.bcm.bootstrap.ICustomRequestMapper

and provide an implementation of method mapRequest . It has the signature:

String mapRequest(String callingClassName,
String methodName,
Object callingThisObject,
Object[] originalParms);

The method returns a string that will replace the original request name supplied in the Custom Request definition. The parameters for the mapRequest() method are:


callingClassName
The name of the instrumented custom request class.
methodName
The name of the instrumented method in the custom request class.
callingThisObject
The object of class callingClassName
originalParms
An array of objects that are the parameters passed to the instrumented method.

These parameters can be interrogated to extract useful contextual information about the request that can be included in the mapped request string. Note that the returned request name string should be less than 256 characters. An example mapper class is shown below:

package com.company;
import com.ibm.tivoli.itcam.toolkit.ai.bcm.bootstrap.ICustomRequestMapper;
import org.apache.http.HttpHost;

public class HttpClientMapper implements ICustomRequestMapper {

public String mapRequest(String callingClassName,
String methodName,
Object callingThisObject,
Object[] originalParms) {

String requestName = "HttpClient" ;

if (callingClassName.equals(
"org.apache.http.impl.client.DefaultRequestDirector" )) {
HttpHost httpHost = (HttpHost) originalParms[0];
requestName += " " +httpHost.toURI();
}
return requestName;
}
}


The ICustomRequestMapper interface is located in jar file
<IITCAMHOME>/toolkit/llib/bcm-bootstrap.jar.
which must be included in the Java compiler classpath when compiling a Custom Request Mapper program.

If you need to explicitly reference any classes passed as parameters to the mapper, then these classes must be defined to the classloader that the mapper program is loaded by. This is also defined in the custom request definition file. Again using our Apache HTTP API example, the entire file now reads:


<gpe>
<bci>
<classesToModify>
<selection>
<Matches>org.apache.http.impl.client.DefaultRequestDirector</Matches>
</selection>
<id>ApacheHttp</id>
<forceClassDefinition>
<className>com.ibm.tivoli.nigel.HttpClientMapper</className>
<jarFile>httpmapper.jar</jarFile>
</forceClassDefinition>
</classesToModify>

<dynamicClassPath>
<path>/u/itcam61fp5</path>
</dynamicClassPath>

<customEdgeRequests>
<edgeRequest>
<requestName>HttpClient</requestName>
<Matches>org.apache.http.impl.client.DefaultRequestDirector</Matches>
<type>application</type>
<methodName>execute</methodName>
<customMapper>com.ibm.tivoli.nigel.HttpClientMapper</customMapper>
</edgeRequest>
</customEdgeRequests>
</bci>
</gpe >


Custom Request Mapper support is planned to available with ITCAM for Application Diagnostics 7.1.0.2 IF10, and ITCAM for WebSphere 6.1.0.6 .


Compiling a Custom Request Mapper

You can compile a Custom Request Mapper with ant, an Eclipse-based IDE such as Rational Application Developer, or simply using the javac command. Make sure that you include the bcm-bootstrap.jar in the classpath:


javac –cp /u/itcam61/toolkit/bcm-bootstrap.jar com/company/itcam/mapper/MyMapper.java

The classes that are used by the Custom Request Mapper must be placed in a jar file to be used by ITCAM. e.g.

jar –cvf mymapper.jar com/company/itcam/mapper/MyMapper.class



Copyright © IBM 2011