User Guide
Developer Guide
Project Documentation
The behaviour of InfraRED can be cutomised by modifying the following property files :
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-monitoring | This 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-enable | This boolean property decides if Infrared should monitor the jdbc executions for the application. | false |
| enable-call-tracing | This 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-threshold | The 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-trace | The number of invocations that need to be displayed in the Last Invocations page of the InfraRED web gui. | 0 |
| collection-strategy | The 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.remotehost | The 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.port | The port number on the remotehost where the Infrared collector listens for the flushed statistics. | 7777 |
| collection-strategy.ccs.flush-frequency | The 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.pool | This 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.maxThreads | The 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-length | The 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 |
The infrared-web.properties file provides some configurable properties on the InfraRED web gui.
| Property | Description | Default Value |
|---|---|---|
| persist-interval | The 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-threshold | The threshold (in ms) above which "hot spots" of the application are displayed in a different color. | 25 |
| web.num-of-sql-queries | The number of SQL queries to be displayed in the Sql Statistics pages of the Infrared web gui. | 5 |
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 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 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.