Enabling Time Travel Debugging (TTD) for Java Runtime
TTD (TimeTravel Debugging) is supported by Thundra Java agent for JVM runtime which means that you can also use it for other JVM based programming languages like Kotlin and Scala as well as pure Java. When TTD (TimeTravel Debugging) is enabled, you can see how your tests and applications behave at every level, giving you in-depth monitoring capabilities along with micro-tracing capability even inside the method by tracing code execution line by line with the snapshots (values) of arguments, local variables and fields. TTD (TimeTravel Debugging) is disabled by default, but can be enabled programmatically (by annotations) or by configuration (environment variables, etc ...).
Time Travel Debugging (TTD) Panel
As offline debugging requires source code, the
thundra-agent-trace-instrument-metadatagen module should be optionally in the dependencies/classpath during compilation. Otherwise, Thundra decompiles the class files on demand to geenerate the source code on the file and as you guess, it may be not be exactly the same as the original source code. thundra-agent-trace-instrument-metadatagen module includes Thundra Java annotation processor and generates metadata (source code, line mappings, etc ...) about classes to be used for tracing at runtime.1
<dependency>
2
<groupId>io.thundra.agent</groupId>
3
<artifactId>thundra-agent-trace-instrument-metadatagen</artifactId>
4
<scope>test</scope>
5
<version>${thundra.version}</version>
6
</dependency>
Copied!
Configuration via Annotations
The
@Traced annotation with the traceLineByLine attribute true must be put onto classes/methods to be debugged.Classes and methods you want to debug can be specified with the
@Traced annotation – they must be marked with this annotation. The class level @Traced annotation is mandatory; if not marked with the annotation, classes won’t be checked or debugged. Additionally, methods can be marked with this annotation as well.To have the
@Traced annotation, you need to add the thundra-agent-api-trace module into your dependencies:Maven
Gradle
1
<dependency>
2
<groupId>io.thundra.agent</groupId>
3
<artifactId>thundra-agent-api-trace</artifactId>
4
<version>${thundra.agent.version}</version>
5
<scope>provided</scope>
6
</dependency>
Copied!
1
dependencies {
2
compileOnly 'io.thundra.agent:thundra-agent-api-trace:${thundraAgentVersion}'
3
}
Copied!
- If the annotation is used on the class, all public methods of the class are debugged by default.
UserService.java
1
...
2
​
3
import io.thundra.agent.api.trace.annotations.Traced;
4
​
5
...
6
​
7
@Traced(traceLineByLine=true)
8
public class UserService {
9
​
10
...
11
12
public User get(String id) {
13
...
14
}
15
​
16
}
Copied!
In the example above, the public
get method is debugged automatically.- If the annotation is used on the method, the specified method is also debugged.
UserService.java
1
...
2
​
3
import io.thundra.agent.api.trace.annotations.Traced;
4
​
5
...
6
​
7
@Traced(traceLineByLine=true)
8
public class UserService {
9
​
10
...
11
​
12
@Traced(traceLineByLine=true)
13
private User getFromCache(String id) {
14
...
15
}
16
​
17
@Traced(traceLineByLine=true)
18
private User getFromRepository(String id) {
19
...
20
}
21
​
22
...
23
}
Copied!
In this example, the
getFromCache and getFromRepository methods are debugged in addition to the get method.If you want to explicitly specify a method to be debug, configure the class level
@Traced annotation by setting the justMarker property and annotate the desired method with the method level @Traced annotation.UserService.java
1
...
2
​
3
import io.thundra.agent.api.trace.annotations.Traced;
4
​
5
...
6
​
7
@Traced(justMarker=true)
8
public class UserService {
9
​
10
@Traced(traceLineByLine=true)
11
public User get(String id) {
12
...
13
}
14
​
15
...
16
​
17
}
Copied!
In this example, only the
get method is debugged because the class level @Traced annotation is marked and only the get method is annotated.Configuration via Environment Variables
To configure TTD (Time Travel Debugging) behavior through environment variables without any code change, the
traceLineByLine attribute of the THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG environment variable must be configured for the packages, classes or the methods to be traced line by line.Environment variable names must be in the
THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG... format, meaning a name must start with the THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG. For example, THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG, THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG1, THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG2, etc ... So multiple definitions can be defined through multiple environment variables starting with THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG environment variable name.Environment variable values must be in the
<class-def>.<method-def>[...] format, The asterisk character (*) in the <class-def> and <method-def> is supported. For example:getmethod in thecom.mycompany.UserServiceclass:com.mycompany.UserService.get- All methods start with
validatein the classcom.mycompany.UserService:com.mycompany.UserService.validate* - All methods (by default only public methods) in the
com.mycompany.UserServiceclass:com.mycompany.UserService.* - All methods (by default only public methods) in the
com.mycompanypackage:com.mycompany.*.*
For example, if you want to debug all methods (by default only public methods are taken care of), the
UserService class over environment variables, the THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG environment variable can be specified as com.mycompany.UserService.*[traceLineByLine=true].Specifying non-public methods
As mentioned above, by default only public methods are counted while debugging. So, if you want to configure non-public methods, you need to specify
methodModifiers attribute which can be configured as a hexadecimal format definition of modifiers from the java.lang.reflect.Modifier class, as shown below:0x00000001means public methods.0x00000002means private methods.0x00000004means protected methods.0x00000008means static methods.0x00000001 | 0x00000002means private or public methods. As shown here, multiple modifiers can be combined with the | character.0x70000000means any method.
Note that, as shown in the examples above, multiple modifiers can be combined with the
| character and this means logical OR.In our example, if we want to debug all public and private methods in the
UserService class over environment variables, the THUNDRA_AGENT_TRACE_INSTRUMENT_TRACEABLECONFIG environment variable can be specified as com.mycompany.UserService.*[traceLineByLine=true,methodModifiers=0x00000001|0x00000002]