A pivotal part of the functionality of the Java Agent is tracing activity within the JVM such that all the activity (both internal and external to the JVM) that results from servicing any given inbound request can be associated with the request itself. In simple cases, each request is processed by one Java thread, making it only necessary to track the processing of that single thread, in a pattern widely known as 'thread per request'.

This was the case for JEE applications prior to the introduction of version 3.0 of the servlet specification (introduced in Java EE 6). In systems where a significant amount of time is spent waiting for external resources, the thread per request model is inefficient because many application threads spend most of their lifetime blocked awaiting external responses.

This observation motivated the asynchronous servlet capabilities provided as part of servlet 3 and also motivates many of the increasingly prevalent reactive frameworks that are in common usage (for example, Play, Akka, Vert.x and Spring Reactor). To correctly correlate transactions end to end in applications using this architectural approach, the agent must follow transactions from thread to thread to enable it to measure and link all the elements of work performed on behalf of each request, irrespective of which thread that work is executed on.

The agent provides two mechanisms for thread tracking, known as 'Constructor mode' and 'Executor mode' (for Java Agent >= 20.11.0).

These are two alternative approaches to the correlation of cross-thread transaction activity:

  • Constructor Mode Thread Tracing - This is the mode that instruments Threads, Runnables, and Callables based on their creation. The agent used this mode formerly as the default mode.
  • Executor Mode Thread Tracing - This tracking mode is the default mode and is based on instrumenting executor frameworks that are commonly used by the majority of applications and frameworks. This mode makes agent operation more efficient, especially in cases where large use of threading is in place, for example, in the presence of the Play, Akka, Vert.x, and Spring Reactor reactive frameworks.

Select the Thread Correlation Mode

You can select the thread correlation mode used by the agent using the async-instrumentation-strategy property within the app-agent-config.xml configuration file.

To run the applications in the Constructor mode, modify the value of async-instrumentation-strategy property, or use the following java command-line option:


The system property takes precedence over the configuration file. You cannot change the configured thread instrumentation mode during runtime.