A thread trace captures the code flow through monitors place throughout the system. This will include any methods associated with classes and packages that were configured through instrumentation on the perfmon4j javaagent.

Thread traces can be output to the TextAppender or a SQLAppender.

This example will capture a thread trace for all webrequest coming into the server with a path of "http://MYSERVER/examples/servlets"

<Perfmon4JConfig enabled='true'>`
  <appender name='myappender' className='org.perfmon4j.TextAppender'/>
  <threadTrace monitorName="WebRequest.examples.servlets" maxDepth="10">
    <appender name='myappender'/>
  </threadTrace>
</Perfmon4JConfig>

The output of this thread trace will look something like this (truncated example):

+-10:57:36:509 (25) WebRequest.examples.servlets 
| +-10:57:36:509 (15) org.apache.catalina.core.StandardEngineValve.invoke 
| | +-10:57:36:509 (5) org.apache.catalina.valves.ErrorReportValve.invoke 
| | | +-10:57:36:509 (0) org.apache.catalina.core.StandardHostValve.invoke 
| | | |   ... Output truncated ... 
| | | +-10:57:36:509 org.apache.catalina.connector.Request.getAttribute 
| | | +-10:57:36:509 (0) org.apache.catalina.valves.ErrorReportValve.report 
| | | +-10:57:36:509 org.apache.catalina.valves.ErrorReportValve.report 
| | +-10:57:36:509 org.apache.catalina.valves.ErrorReportValve.invoke 
| +-10:57:36:509 org.apache.catalina.core.StandardEngineValve.invoke 
+-10:57:36:509 WebRequest.examples.servlets 

Depending on the code instrumentation present, and the path of execution thread trace output can be very verbose. Also since thread traces are temporarily held in memory (until the completion of the code path) there is a limit on the total number of lines that will be captured. To get around these limitations there are two attributes that can be added to the thread trace to limit the size of the output.

• maxDepth - Will limit the call stack depth captured by the trace
• minDurationToCapture - Will limit code segments captured and reported to those that take in excess of this duration (in milliseconds)

Thread traces are also relatively heavy weight (particularly compared to the very low overhead associated with all other Perfmon4j monitors). Sometimes you just want to sample a percentage of thread executions to evaluate the detailed code path. For example if the servlet "http://MYSERVER/examples/servlets" is executed 100s of times per minute I might only want to sample one instance out of 100. The following attribute is useful for this configuration.

• randomSamplingFactor - Approximately 1 out of each randomSamplingFactor invocations will result in a thread trace being captured.

Example with extended attributes:

<Perfmon4JConfig enabled='true'>`
  <appender name='myappender' className='org.perfmon4j.TextAppender'/>
  <threadTrace monitorName="WebRequest.examples.servlets" maxDepth="10" minDurationToCapture='10' randomSamplingFactor='100'>
    <appender name='myappender'/>
  </threadTrace>
</Perfmon4JConfig>

Another option to limit the number of thread traces that are captured is to include a trigger in the configuration. A trigger is a conditional element that when satisfied will consider the thread a candidate to be captured.

There are 5 types of triggers. The first 3 types are used to limit thread traces to code that is executed in response to an HTTP request:

• HTTPRequestTrigger- This trigger is satisfied when the specified parameter name and value is found on the initiating request.
• HTTPSessionTrigger - This trigger is satisfied when the specified property name and value is found set on the HTTPSession associated with the request.
• HTTPCookieTrigger - This trigger is satisfied when the specified cookie name and value is found on the initiating request.

The next 2 types are associated with code specific values and can be used for non-http request initiated code paths:

• ThreadPropertyTrigger - A property with the specified name and value has been associated with the thread executing the operation.
• ThreadNameTrigger - The executing thread name matches the supplied parameter.

The following example will only capture a thread trace when the incoming request HTTP request contains a parameter of userName with a value of Dave:

<Perfmon4JConfig enabled='true'>`
  <appender name='myappender' className='org.perfmon4j.TextAppender'/>
  <threadTrace monitorName="WebRequest.examples.servlets">
    <appender name='myappender'/>
    <Triggers>
       <HTTPRequestTrigger name="userName" value="Dave"/>
    </Triggers>
  </threadTrace>
</Perfmon4JConfig>