Installation

Note: The installation steps described here is one way to integrate InfraRED with an application. There is a second, automated way of doing it using an Ant task. It is recommended that you try the steps described below, get InfraRED working with the application, and then later move on to the Ant-based integration.

In general, integrating InfraRED with an application involves three steps:

  1. Download InfraRED
  2. Prepare the JVM on which the application is running
  3. Prepare the application
  4. Install the web GUI of InfraRED

Download InfraRED

Download InfraRED latest release from SourceForge. Unzip the archive somewhere into your disk. In what follows, INFRARED_HOME refers to the directory where you have the uncompressed the infrared distribution.

Preparing the JVM

InfraRED uses AspectWerkz internally; hence to integrate InfraRED with an application, one needs to integrate AspectWerkz on the JVM on which the application is running. The detailed steps are described on the AspectWerkz website, but here we outline the recommended procedures.

Preparing Sun 1.3 and 1.4 JVMs

If you are using Sun 1.3 or 1.4 JVMs you need to modify the bootclasspath with an enhanced classloader implementation. This involves two steps:

  1. Prepare the enhanced classloader

    InfraRED ships with an aspectwerkz-core-2.0.jar. Using that file, run the following commands: 

    set CLASSPATH=%INFRARED_HOME%\aspectwerkz-core-2.0.jar;%JAVA_HOME%\lib\tools.jar
java org.codehaus.aspectwerkz.hook.Plug -target %INFRARED_HOME%\enhanced.jar

    This creates a file enhanced.jar in INFRARED_HOME. (AspectWerkz documentation refers to this as 'Prepared bootclasspath').

  2. Setting up the bootclasspath

    Prepend enhanced.jar created above to the bootclasspath, append aspectwerkz-core-2.0.jar to the bootclasspath, and add aspectwerkz and infrared jars to the classpath. The following section describes this for Weblogic, Tomcat and JBoss servers.

    • Weblogic:

      You need to edit the DOMAIN_HOME\startWeblogic.cmd(sh) or DOMAIN_HOME\startManagedWeblogic.cmd(sh) file to add: 

                
@REM Integrate InfraRED with Weblogic running on Sun 1.3/4 JVM
set JAVA_OPTIONS=-Xbootclasspath/p:%INFRARED_HOME%\enhanced.jar -Xbootclasspath/a:%INFRARED_HOME%\aspectwerkz-core-2.0.jar %JAVA_OPTIONS%
set CLASSPATH=%INFRARED_HOME%\infrared-aspectsystem-all-XX.jar;%INFRARED_HOME%\infrared-agent-all-weblogic-XX.jar;%CLASSPATH%

      You can add these lines anywhere in the file before the command to launch the VM.

    • Tomcat:

      You need to:

      • edit the TOMCAT_HOME\bin\setclasspath.bat(sh) to add:

        @REM Integrate InfraRED with Tomcat running on Sun 1.3/4 JVM
set JAVA_OPTS=-Xbootclasspath/p:%INFRARED_HOME%\enhanced.jar -Xbootclasspath/a:%INFRARED_HOME%\aspectwerkz-core-2.0.jar %JAVA_OPTS%

        You can add these lines anywhere in the file.

      • copy the file INFRARED_HOME\infrared-aspectsystem-all-XX.jar into TOMCAT_HOME\common\endorsed directory.
      • copy the infrared-agent-all-servlet-XX.jar into TOMCAT_HOME\common\lib directory.

    • JBoss:

      You need to:

      • edit the JBOSS_HOME\run.bat(sh) to add:

        @REM Integrate InfraRED with JBoss running on Sun 1.3/4 JVM
set JAVA_OPTS=-Xbootclasspath/p:%INFRARED_HOME%\enhanced.jar -Xbootclasspath/a:%INFRARED_HOME%\aspectwerkz-core-2.0.jar %JAVA_OPTS%

        You can add these lines anywhere in the file before the command to launch the VM.

      • copy the file INFRARED_HOME\infrared-aspectsystem-all-XX.jar into JBOSS_HOME\lib\endorsed directory.
      • copy the file INFRARED_HOME\infrared-agent-all-jboss-XX.jar into JBOSS_HOME\server\default\lib directory.

Preparing BEA JRockit 7 and 8.1 JVM

If you are using BEA JRockit JVM versions 7 or 8.1, you need to add the -Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor JVM switch, and add the infrared-aspectsystem-all-XX.jar and infrared-agent-all-weblogic-XX.jar jars to the server's CLASSPATH. These jars comes bundled with InfraRED distribution.

You need to edit the DOMAIN_HOME\startWeblogic.cmd(sh) or DOMAIN_HOME\startManagedWeblogic.cmd(sh) file to add: 

          
@REM Integrate InfraRED with Weblogic running on JRockit
set JAVA_OPTIONS=-Xmanagement:class=org.codehaus.aspectwerkz.extension.jrockit.JRockitPreProcessor %JAVA_OPTIONS%
set CLASSPATH=%INFRARED_HOME%\infrared-aspectsystem-all-XX.jar;%INFRARED_HOME%\infrared-agent-all-weblogic-XX.jar;%CLASSPATH%

You can add these lines anywhere in the file.

Preparing Sun 1.5 JVM

If you are using Sun 1.5 JVM, you need to add a preMain Java agent to the VM.

  • Tomcat:

    You need to:

    • edit the TOMCAT_HOME\bin\setclasspath.bat(sh) to add:

      @REM Integrate InfraRED with Tomcat running on Sun 1.5 JVM
set JAVA_OPTS=-javaagent:INFRARED_HOME/aspectwerkz-jdk5-2.0.jar %JAVA_OPTS%

      You can add these lines anywhere in the file.

    • copy the file INFRARED_HOME\infrared-aspectsystem-all-XX.jar into TOMCAT_HOME\common\endorsed directory.
    • copy the infrared-agent-all-servlet-XX.jar into TOMCAT_HOME\common\lib directory.

  • JBoss:

    You need to:

    • edit the JBOSS_HOME\run.bat(sh) to add:

      @REM Integrate InfraRED with JBoss running on Sun 1.5 JVM
set JAVA_OPTS=-javaagent:INFRARED_HOME/aspectwerkz-jdk5-2.0.jar %JAVA_OPTS%

      You can add these lines anywhere in the file before the command to launch the VM.

    • copy the file INFRARED_HOME\infrared-aspectsystem-all-XX.jar into JBOSS_HOME\lib\endorsed directory.
    • copy the file INFRARED_HOME\infrared-agent-all-jboss-XX.jar into JBOSS_HOME\server\default\lib directory.

Perparing the application

The application needs to be prepared for InfraRED. The following section describes doing this using AspectWerkz load-time weaving. It involves three steps:

  1. Copy the file INFRARED_HOME\props\infrared-agent.properties to a location from where it can be loaded by the Classloader which loads the application. For a WAR web application, this involves copying INFRARED_HOME\props\infrared-agent.properties into WEB-INF/classes. For an EAR application in Weblogic, this involves copying INFRARED_HOME\props\infrared-agent.properties into APP-INF/classes. For an EAR application in JBoss, INFRARED_HOME\props\infrared-agent.properties should be put in the root of the ear.

    The contents of infrared-agent.properties file govern the InfraRED configuration. The sample provided at INFRARED_HOME\props\infrared-agent.properties suffices as a good default. The various configuration options are explained in the Configuration page.

  2. Create a file META-INF/aop.xml that can be loaded by the Classloader which loads the application. For a WAR web application, this can be put in WEB-INF/classes (so that we have the file WEB-INF/classes/META-INF/aop.xml). For an EAR application in Weblogic, this can be put in APP-INF/classes (so that we have the file APP-INF/classes/META-INF/aop.xml). For an EAR application in JBoss, this has to be put in the META-INF dir in the root of the ear.

    This is a regular AspectWerkz aspect definition file, but contents of this determine the layers of the application that would be identified by InfraRED. A sample is give below.

                           
<!DOCTYPE aspectwerkz PUBLIC
    "-//AspectWerkz//DTD//EN"
    "http://aspectwerkz.codehaus.org/dtd/aspectwerkz2.dtd">

<aspectwerkz>
    <system id="my.app">      
        <exclude package="net.sf.infared.*"/>        
        
        <!-- 
            All executions in com.my.app.layer1 package and its subpackages
            will be recorded as LayerOne
        -->
        <aspect class="net.sf.infrared.aspects.api.ApiAspect"
                deployment-model="perClass" name="LayerOne"> 
            <param name="layer" value="LayerOne"/>
            <pointcut name="methodExecution" 
                      expression="execution(public * com.my.app.layer1.*...*(..))"/>
            <advice name="collectMetrics(StaticJoinPoint sjp)" type="around" bind-to="methodExecution"/>
        </aspect>
    
        <!-- 
            All executions in com.my.app.layer2 package and its subpackages
            will be recorded as LayerTwo
        -->
        <aspect class="net.sf.infrared.aspects.api.ApiAspect"
                deployment-model="perClass" name="LayerTwo"> 
            <param name="layer" value="LayerTwo"/>
            <pointcut name="methodExecution" 
                      expression="execution(public * com.my.app.layer1.*...*(..))"/>
            <advice name="collectMetrics(StaticJoinPoint sjp)" type="around" bind-to="methodExecution"/>
        </aspect>
    </system>
</aspectwerkz>

    Layers are typically identified by packages.

    More details on how to identify various layers are given in the Configuration page

  3. Add InfraRED application startup listener to.

    1. For a WAR web application, add the following entries to the WEB-INF/web.xml file. 
                            
<web-app>
    ..    
    <filter>
        <filter-name>infrared</filter-name>
        <filter-class>net.sf.infrared.aspects.servlet.InfraREDServletFilter</filter-class>
    </filter>
    ..
    <filter-mapping>
        <filter-name>infrared</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    ..
    <listener>
        <listener-class>net.sf.infrared.agent.setup.InfraREDServletContextListener</listener-class>
    </listener>
    ..
</web-app>
    2. For an EAR application in Weblogic, add the following entries to the META-INF/weblogic-application.xml file. 
                            
<weblogic-application>
    .. 
    <listener>
        <listener-class>net.sf.infrared.weblogic.setup.InfraRedApplicationLifeCycleListener</listener-class>
    </listener>
    ..
</weblogic-application>
    3. For an EAR application in JBoss, copy the INFRARED_HOME/infrared-mbean-XX.sar into the EAR and add the following entries to the META-INF/jboss-app.xml file. 
                            
<jboss-app>
    .. 
    <module>
        <service>infrared-mbean-XX.sar</service>
    </module>
    ..
</jboss-app>

      Note that 'XX' here refers to the version of InfraRED.

Install the web GUI of InfraRED

InfraRED web GUI can be found in INFRARED_HOME/infrared-web-all-XX.war. This can be installed on any J2EE web container. Data collected by InfraRED can be viewed with this web application.