<<Previous | Next>>
Please note that the installation guidelines detailed in this page are only applicable to the
Infrared-2.1-beta release. For all later versions of Infrared, please refer the documentation
bundled with the respective release.
Following are the 3 basic steps to prepare the application for monitoring,
- Integration of InfraRED with the application.
- Addition of classpaths, configuration of datasource etc.
- Deployment of application and infrared.war and accessing InfraRED site.
Step 1:
Note: Ant Version 1.5 or higher needs to be used.
Download the latest release of InfraRED and unzip it in a folder. This folder will henceforth be called infrared.home. Depending upon the application server / Web Server used and the format of distribution i.e. Ear/War, choose the set of targets from Table 1. Insert these targets in your build-script to integrate InfraRED with your application. (These xml snippets are also available in the file build-snippet.txt under scripts folder in the release zip).
Integration of InfraRED with the application is composed of following steps.
- Instrumentation of application (Insertion of byte code to collect performance data).
- Addition of relevant InfraRED jars in the appropriate location in the application.
- Insertion of appropriate servlet filters, application life cycle listener and listener servlet in the application.
- Addition of infrared properties file in the appropriate location.
Table 1
| Weblogic SP3 (Ear) |
<taskdef name="integrate" classname="net.sf.infrared.antTask.Integrate">
<classpath>
<pathelement location="${infrared.home}/infrared-antTask.jar"/>
<pathelement location="${infrared.home}/dependency-jars/aspectjtools-1.2.jar"/>
</classpath>
</taskdef>
<target name="integrateInfraRED">
<integrate earFile="${Application.ear}" destEarFile = "${Instrumented.app.ear}"
infraredHome="${infrared.home}" centralCollection="false" >
<classpath>
<pathelement location="${weblogic.jar.path}"/>
<!-- path of dependency classes/jars -->
</classpath>
</integrate>
</target>
|
| Weblogic SP3 (War) |
<taskdef name="integrate" classname="net.sf.infrared.antTask.Integrate">
<classpath>
<pathelement location="${infrared.home}/infrared-antTask.jar"/>
<pathelement location="${infrared.home}/dependency-jars/aspectjtools-1.2.jar"/>
</classpath>
</taskdef>
<target name="integrateInfraRED">
<integrate webWar="${Application.war}" destWebWar="${Instrumented.app.war}" infraredHome="${infrared.home}">
<classpath>
<pathelement location="${weblogic.jar.path}"/>
<!--path of dependency classes/jars -->
</classpath>
</integrate>
</target>
|
| JBoss (Ear) |
<taskdef name="integrate" classname="net.sf.infrared.antTask.Integrate">
<classpath>
<pathelement location="${infrared.home}/infrared-antTask.jar"/>
<pathelement location="${infrared.home}/dependency- jars/aspectjtools-1.2.jar"/>
</classpath>
</taskdef>
<target name="integrateInfraRED">
<integrate earFile="${Application.ear}" destEarFile = "${Instrumented.app.ear}" infraredHome="${infrared.home}"
centralCollection="true|false" appserver="jboss" applicationName="${app-name}" portNumber="${port-number}">
<classpath>
<pathelement location="${javax.servlet.jar}"/>
<pathelement location="${jboss.j2ee.jar}"/>
<!--path of dependency classes/jars -->
</classpath>
</integrate>
</target> |
| JBoss (War) |
<taskdef name="integrate" classname="net.sf.infrared.antTask.Integrate">
<classpath>
<pathelement location="${infrared.home}/infrared-antTask.jar"/>
<pathelement location="${infrared.home}/dependency-jars/aspectjtools-1.2.jar"/>
</classpath>
</taskdef>
<target name="integrateInfraRED">
<integrate webWar="${Application.war}" destWebWar="${Instrumented.app.war}"
infraredHome="${infrared.home}" appserver="jboss" portNumber="${port-number}">
<classpath>
<pathelement location="${javax.servlet.jar}"/>
<pathelement location="${jboss.j2ee.jar}"/>
<!--path of dependency classes/jars -->
</classpath>
</integrate>
</target> |
| Tomcat (War) |
<taskdef name="integrate" classname="net.sf.infrared.antTask.Integrate">
<classpath>
<pathelement location="${infrared.home}/infrared-antTask.jar"/>
<pathelement location="${infrared.home}/dependency-jars/aspectjtools-1.2.jar"/>
</classpath>
</taskdef>
<target name="integrateInfraRED">
<integrate webWar="${Application.war}" destWebWar="${Instrumented.app.war}"
infraredHome="${infrared.home}" appserver="tomcat" portNumber="${port-number}">
<classpath>
<!--path of dependency classes/jars -->
</classpath>
</integrate>
</target> |
Dependency Jars/Classes - Application Ear/War may depend on external jar or classes required to build it, but which are not packaged with the application Ear/War. Such jars or classes needed for running the integrateInfraRED target can be specified under the classpath element. For example, if you are using Weblogic, since weblogic.jar is not part of the application and is required for building the application, it can be specified under the classpath element.
InfraRED has defined an Ant Task – Integrate which integrates InfraRED with the given application for gathering performance data. The various attributes of this ant task are explained here. Set the attribute values in the targets accordingly. Include any optional attributes in the integrate task as required.
Table 2
Attribute |
Description |
Optional/Mandatory |
earFile |
Name of the application ear file with fully qualified path. |
Optional (Either of earFile or webWar should be defined) |
destEarFile |
Name of the integrated ear file with the fully qualified path. Integrated Ear will be created in this location with this given name. |
Mandatory if earFile has been defined |
webWar |
Name of the application war file with fully qualified path. |
Optional (Either of earFile or webWar should be defined) |
destWebWar |
Name of the integrated war file with the fully qualified path. Integrated War will be created in this location with this given name. |
Mandatory if webWar has been defined |
infraredHome |
Folder where the Infrared zip has been unzipped. |
Mandatory |
appserver |
Name of the app server - "weblogic | jboss | tomcat", default value: "weblogic" |
Optional. If not specified, will default to "weblogic" |
applicationName |
Name of the application. This will be used to name the instance of the application. In case of Weblogic, this is queried from the MBean. Since MBean is not available in JBoss, this property has to be specified. In case of Wars, instance name is picked up from the <display-name> node in the web.xml |
Relevant only if appserver=jboss and Ear is the format of distribution. |
portNumber |
The port number on which you will run your application. This will be used to name the instance of the application. In case of Weblogic, this is queried from the MBean. Since MBean is not available in JBoss, this property has to be specified. |
Relevant only if appserver=jboss and Ear is the format of distribution. |
centralCollection |
Collection Strategy for the performance data. InfraRED provides 2 collection strategies – remote and local. Multiple application instances on one or more servers/clustered applications can be integrated with InfraRED and the performance data can be collected centrally in one place. This central point of performance data collection shall be remote to the applications in this case. Alternatively, the performance data may be collected locally. Valid values for this attribute are true/false. True implies remote collection strategy where the data is collected centrally. |
Optional. Valid values for this attribute are true/false. Default value: "false".
|
centralServer |
In case, you want to deploy infrared.war on a different machine and collect data there. |
Optional. Default value: "localhost". |
AppInfLibJars |
For Weblogic Appserver application, if you want to instrument jars present in the APP-INF/lib dir of your application, then list them (comma separated) in this property. |
Optional. Useful only for Weblogic. |
instrument |
As explained in the beginning, Integrate task instruments the application as part of the overall integration of InfraRED with the application. Set this property to false, to perform the InfraRED integration without instrumentation of the classes. This can be used when AspectWerkz is used for load time weaving of the application. |
Optional. Valid Values - true|false. Default value: "true" |
aspectPath |
If you have created your own aspect classes and advices, give the path of the jar containing those classes. Default Value: ${infrared.home}/infrared-generic-aspects.jar |
Optional |
| fork |
Determines whether the instrumentation of classes needs to be forked. Possible values true/false. Default - false. |
Optional. Default - false |
Run the integrateInfraRED target to integrate InfraRED with the application.
After running the above ant Task, you will find an aspected-ear (or war) created at the position specified.
Step 2:
After the STEP 1 is complete, you will see an aspected ear/war created. This is the InfraRED integrated application you need to deploy. But before you start your server and deploy the application, follow steps in table 3.
Table 3
Weblogic SP3 |
-
Copy infrared-bootstrap.jar, \dependency-jars\p6Spy.jar and \dependency-jars\aspectjrt-1.2.jar from the infrared release, to a folder (typically in your ${bea-home}\weblogic81\server\ext folder) and include these three jars in your Weblogic server’s classpath. To do this, include these three jars in the classpath specified in the startWebLogic.cmd file.
-
Copy spy.properties file (from %INFRARED_HOME%\setup) in a folder (say, bea-home\weblogic81\server\ext\spy) and include this directory in your Weblogic-server’s classpath, i.e. include this directory in the classpath specified in the startWebLogic.cmd file.
-
Make a P6Spy connection pool:
-
For XA-connection Pool (supported only for Oracle XA Connection):
- Create a new connection pool choosing the other option in the driver list.
- Specify net.sf.infrared.bootstrap.jdbc.oracle.InfraREDOracleXADataSource as the driver.
- The url jdbc:oracle:oci:@<db tns name> for oracle 8i oci driver
- Make sure real driver property in spy.properties is set to oracle.jdbc.driver.OracleDriver
-
For normal JDBC Connection Pool:
- Create a new connection pool choosing the other option in the driver list
- Specify com.p6spy.engine.spy.P6SpyDriver as the driver.
- Specify the Url for the connection. For e.g. the Url for oracle 8i oci driver will be jdbc:oracle:thin:@<db tns name>
- Make sure real driver property in spy.properties is set to the correct driver. For e.g., for oracle 8i oci driver real driver property should be set to oracle.jdbc.driver.OracleDriver
-
Point your data-source to the newly created connection-pool.
|
Jboss |
-
Copy infrared-bootstrap.jar, \dependency-jars\p6Spy.jar and \dependency-jars\aspectjrt-1.2.jar from the infrared release, to folder %JBOSS_HOME%/server/default/lib, which will put these jars in classpath.
-
Copy spy.properties file (from %INFRARED_HOME%\setup) to folder %JBOSS_HOME%/server/default/conf. Folder, %JBOSS_HOME%/server/default/conf is in classpath by default.
-
Make a P6Spy connection pool:
- For XA-connection Pool / Normal JDBC Connection Pool
Take oracle-xa-ds.xml for XA-Connection pool and oracle-da.xml for normal jdbc connection pool from %JBOSS_HOME%/docs/examples/jca directory and make following entries,
<local-tx-datasource>
<jndi-name>jndi-name</jndi-name>
<connection-url>jdbc:oracle:oci:@youroracle-tns-name</connection-url>
<driver-class>com.p6spy.engine.spy.P6SpyDriver</driver-class>
<user-name>user-name</user-name>
<password>pswd</password>
<exception-sorter-class-name> fully-qualified-class-name</exception-sorter-class-name>
</local-tx-datasource>
- Put oracle-xa-ds.xml in %JBOSS_HOME%/server/default/deploy directory.
|
Tomcat |
-
Copy infrared-bootstrap.jar, \dependency-jars\p6Spy.jar and \dependency-jars\aspectjrt-1.2.jar from the infrared release, to folder %TOMCAT_HOME%/common/lib/, which will put these jars in classpath.
-
Copy spy.properties file (from %INFRARED_HOME%\setup) to folder %TOMCAT_HOME%\conf. Folder, and modify the file %TOMCAT_HOME%\bin\setclasspath.bat to set this folder in classpath. Append ;%TOMCAT_HOME%\conf; to the CLASSPATH element.
-
Modify server.xml to use p6spy driver. Replace the value of parameter 'driverClassName' to com.p6spy.engine.spy.P6SpyDriver
|
STEP 3:
Based on the choice of centralized collection take the following steps
Table 4
centralCollection=true
(For Wars, centralCollection=true by default) |
- Deploy the aspected ear/war on your application server and run it as you would usually do.
- Deploy infrared.war on the central server where you would like centralized collection to happen.
- Access the performance statistics using infrared-ui at following URL: http://localhost:7001/infrared
|
centralCollection=false |
- Deploy the aspected ear/war on your application server and run it as you would usually do. If centralCollection=false was chosen then infrared.war will be the part of your ear/war. And infrared.war will get deployed as part of your application.
- Access the performance statistics using infrared-ui at following URL: http://localhost:7001/<application-context>/infrared
|
<<Previous | Next>> |
