Configuration

The behaviour of InfraRED can be cutomised by modifying the following property files :

  1. infrared-agent.properties
  2. infrared-web.properties
Sample files are available under the props folder in the release zip.

infrared-agent.properties

The following properties in infrared-agent.properties can be modified. If omitted, InfraRED assumes suitable defaults for each of these properties. As is evident from the table below, the default behaviour of InfraRED does not to monitor the application.

Property Description Default Value
enable-monitoringThis boolean property decides if Infrared should monitor the application. If this property is set to false, no data will be visible on the Infrared web gui.false
jdbc-monitoring-enableThis boolean property decides if Infrared should monitor the jdbc executions for the application.false
enable-call-tracingThis boolean property decides if Infrared should record call traces. A call trace is a sequence of executions in an application and the Infrared web gui makes use of a tree structure to display the call trace.false
prune-thresholdThe threshold value (in milliseconds) for any execution to be recorded in InfraRED. Executions taking lesser time than this value (in ms) would be pruned by Infrared.3000
last-invocations-to-traceThe number of invocations that need to be displayed in the Last Invocations page of the InfraRED web gui.0
prepared-statement-monitoring-enableThis boolean property decides if Infrared should keep track of the arguments for a SQL query bound to a PreparedStatement.false
mbean-server-providerThe class name of the MBean server provider. The legal values are net.sf.infrared.weblogic.configmgmt.WLSMBeanServerProvider for Weblogic server and net.sf.infrared.jboss.configmgmt.JBossMBeanServerProvider for JBoss server. The Infrared MBean can be used to configure the Infrared properties using JMX based tools like MC4J Management Console. The InfraredProperties MBean exposes the following properties as attributes :enable-monitoring, jdbc-monitoring-enable, enable-call-tracing, prune-thresholdnone
collection-strategyThe class name of the strategy that needs to be employed for the collection of the metrics of the application. Infrared currently supports only CentralizedCollectionStrategy and the corresponding class name is net.sf.infrared.agent.transport.impl.CentralizedCollectionStrategy. The default DoNothingCollectionStrategy, as the name indicates, acts as a dummy collection strategy implemetation.net.sf.infrared.agent.transport.impl.DoNothingCollectionStrategy
collection-strategy.ccs.remotehostThe hostname of the machine that runs the infrared collector. The collected statistics for the application are flushed to the collector in the remotehost making use of a socket connection.localhost
collection-strategy.ccs.portThe port number on the remotehost where the Infrared collector listens for the flushed statistics.7777
collection-strategy.ccs.flush-frequencyThe frequency at which the collected statistics for the application need to be flushed to the collector in the remotehost. The flush frequency value needs to be optimised for good performance. The higher the value, the longer the statistics need to be stored at the application end and hence the greater will be the required memory. On the other hand, a lower frequency implies larger network traffic.30000
collection-strategy.ccs.poolThis boolean property decides if the collected statistics need to be maintained using thread pools in the application end before they are flushed to the collector in the remote host.true
collection-strategy.ccs.pool.maxThreadsThe maximum number of threads permissible in the thread pool.This property is applicable only if the collection-strategy.ccs.pool is set to true.1
collection-strategy.ccs.pool.buffer-lengthThe capacity of the pool buffer indicating the number of elements that can be held. This property is applicable only if the collection-strategy.ccs.pool is set to true.100

infrared-web.properties

The infrared-web.properties file provides some configurable properties on the InfraRED web gui.

Property Description Default Value
persist-intervalThe interval (in milliseconds) at which the collected statistics for the application are written to the database. All the statistics that reach the collector within this time interval will be merged.300000
web.color-thresholdThe threshold (in ms) above which "hot spots" of the application are displayed in a different color.25
web.num-of-sql-queriesThe number of SQL queries to be displayed in the Sql Statistics pages of the Infrared web gui.5

Aspects provided with InfraRED

InfraRED can track the timing of various types of executions in an application - SQL queries, JSP rendering, Hibernate queries, method executions etc. These are configured by writing AOP aspects. InfraRED ships with a set of aspects which are sufficient for typical usage. This section describes those aspects (Note: We use AspectWerkz XML aspects in this section although we support both AspectWerkz and AspectJ AOP frameworks).

Api Aspect

Api Aspect can be used to track execution of regular Java methods. Also, methods can be categorized into different layers. Typical usage looks like:

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

<aspectwerkz>
    <system id="my.app">      
        <exclude package="net.sf.infared.*"/>        
        
        <!-- 
            All public methods 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 public methods 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>      
 
                

In the above fragment, all public methods in com.my.app.layer1 package and its subpackages will be recorded as LayerOne and those in com.my.app.layer2 package and its subpackages will be recorded as LayerTwo. More details on the syntax of the XML file can be found in the AspectWerkz documentation.

Hibernate Aspect

Hibernate Aspect collects performance information of execution of Hibernate queries. Typical usage is:

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

<aspectwerkz>                   
    <system id="infrared.system.hibernate">
        <exclude package="net.sf.infared.*"/>
        <include package="net.sf.hibernate.*"/>
        <include package="org.hibernate.*"/>
                                        
        <aspect class="net.sf.infrared.aspects.hibernate.Hibernate2Aspect"
            deployment-model="perJVM">            
            
            <pointcut name="hib2Query(net.sf.hibernate.Query query)" 
            expression="execution(public java.util.List org.hibernate.Query+.list()) AND target(query)"/>
            
            <pointcut name="hib2Find(String queryString)" 
            expression="execution(public * net.sf.hibernate.Session+.find()) AND args(queryString, ..)"/>
                        
            <advice name="aroundQueryExecution(net.sf.hibernate.Query q, StaticJoinPoint sjp)" 
            type="around" bind-to="hib2Query(q)"/>
                
            <advice name="aroundQueryExecution(String q, StaticJoinPoint sjp)" 
            type="around" bind-to="hib2Find(q)"/>         
        </aspect>        
        
        <aspect class="net.sf.infrared.aspects.hibernate.Hibernate3Aspect"
            deployment-model="perJVM">
            
            <pointcut name="hib3Query(org.hibernate.Query query)" 
                expression="execution(public java.util.List org.hibernate.Query+.list()) AND target(query)"/>
            
            <pointcut name="hib3Find(String queryString)" 
                expression="execution(public * org.hibernate.Session+.find()) AND args(queryString, ..)"/>

            <advice name="aroundQueryExecution(org.hibernate.Query q, StaticJoinPoint sjp)" 
                type="around" bind-to="hib3Query(q)"/>
                
            <advice name="aroundQueryExecution(String q, StaticJoinPoint sjp)" 
                type="around" bind-to="hib3Find(q)"/>
        </aspect>                
    </system>
</aspectwerkz>     

                

Note that most applications might not be using both Hibernate 2 & 3, so only one of the above two aspects need to be configured.

Persistence of Infrared statistics on an Oracle Database

Infrared statistics are persisted to an in-built HSQL database by default. However, the system can be configured to persist the data on to an Oracle database. The steps to be followed are :

  1. Configure a DataSource with IRED_DATASOURCE as the jndi lookup name.
  2. Run the SQL script provided below on the database to create the necessary tables.

CREATE TABLE LAYER_TIMES(APP_NAME VARCHAR(100) NOT NULL,HOST_NAME VARCHAR(100) NOT NULL,LAYER VARCHAR(50) NOT NULL,DURATION NUMBER,INSERT_TIME TIMESTAMP);
CREATE TABLE EXECUTION_TIMES(APP_NAME VARCHAR(150) NOT NULL,HOST_NAME VARCHAR(150) NOT NULL,HIERARCHICAL_LAYER VARCHAR(300),LAYER VARCHAR(150),CLASS_NAME VARCHAR(250),NAME VARCHAR(1000),EXEC_COUNT NUMBER,TOT_INCLUSIVE_TIME NUMBER,MAX_INCLUSIVE_TIME NUMBER,MIN_INCLUSIVE_TIME NUMBER,TOT_EXCLUSIVE_TIME NUMBER,MAX_EXCLUSIVE_TIME NUMBER,MIN_EXCLUSIVE_TIME NUMBER,TIME_OF_FST_EXEC NUMBER,TIME_OF_LST_EXEC NUMBER,INCLUSIVE_FST_EXEC_TIME NUMBER,INCLUSIVE_LST_EXEC_TIME NUMBER,EXCLUSIVE_FST_EXEC_TIME NUMBER,EXCLUSIVE_LST_EXEC_TIME NUMBER,INSERT_TIME TIMESTAMP);
CREATE TABLE AGG_OPERATION_TREE(APP_NAME VARCHAR(100) NOT NULL,HOST_NAME VARCHAR(100) NOT NULL,TREE BLOB,INSERT_TIME TIMESTAMP);