Replaying a recording¶
Quick start¶
Unzip
LR4J-Record-*.zip(this creates a directory namedlr4j).Replay the recording:
$LR4J_HOME/bin/lr4j_replay --input /path/to/recording.undo --port 9000
Connect IntelliJ to port 9000 using the Undo Replay (Remote) run configuration, or a Remote JVM Debug configuration (see Replaying and Time travel debugging in IntelliJ).
Requirements¶
A Linux environment with access to the recording file. Usually it’s simplest if this is the same environment in which the application was recorded. However if the recording environment is transient - e.g. a container or on-demand cloud instance - it will be easier to replay in a more interactive environment such as a physical machine, a VM, WSL2, or a scratch container running a supported Linux distribution.
A JDK for any supported Java version. The JDK used for replay does not need to match the JDK used to make the recording.
The ability to copy the Undo for Java replay tools into this environment.
(Optionally) a copy in this environment of the same build of jar files as supplied to Java at record time.
IntelliJ IDEA running in the same Linux environment as your application, or running on a separate Windows, macOS or Linux machine. Refer to Getting started if you don’t already have the Undo for Java plugin installed and setup in IntelliJ.
- If the environment is a remote machine, or a VM or container running on your local machine:A port (default 9000) opened into the environment for IntelliJ to connect over.
Recordings made with the recording agent and recordings made with live-record are both supported, including recordings made without the JVM options that the agent requires (see JVM options).
Inspecting a recording¶
Added in version 10.0.
lr4j_recording_info prints a summary of a recording file, read directly from the file: no engine, license key, or replay session is needed.
$LR4J_HOME/bin/lr4j_recording_info /path/to/recording.undo
The output covers the recorded program (termination reason, recorded time range, bbcount range, architecture, memory requirements), the system and Undo Engine version that created the recording, a size breakdown of the recording file, and the recorded Java information: the Java version, the recorded JVM’s version banner, and whether the recording was made with the recording agent or with live-record. Use it to check which JDK a recording needs before replaying it. In IntelliJ, Recording Properties shows the same summary, and has an example of it.
Replaying¶
The Undo for Java IntelliJ plugin provides these Run/Debug configurations:
Windows or macOS¶
Open your project in IntelliJ if it’s not already open.
Under File › Project Structure… › SDKs check that the JDK version matches the version of the JRE used to make the recording.
From the Run menu choose Edit Configurations and press the + button at the top left of the Run/Debug Configurations dialog.
Add a Remote JVM Debug configuration
Specify the machine running your application as the Host. Use
localhostif you’re replaying on Linux, or in a VM or container running on your local machine.Adjust the Port setting to match the port that you opened up into the remote environment above.
Ignore the recommended
Command line arguments for remote JVMas we are using our own replay tool which emulates a remote JDWP agent
In the replay environment:
Unzip the file
LR4J-Record-*.zip. This creates a directory namedlr4j.To replay a recording:
$LR4J_HOME/bin/lr4j_replay --input /path/to/recording.undo
$LR4J_HOME/bin/lr4j_replay --input /path/to/recording.undo --port PORT
Linux¶
As an alternative to the above, on Linux there is a Run Configuration which can be used to launch the replay session directly.
First, set Settings › Tools › Undo for Java › Replay tool directory to the location of the unzipped
LR4J-Record-*.zipdirectory.The plugin creates an Undo Replay (Recording) run configuration when you open a project, which asks for the recording to replay when you start it. You can also right-click a
.undofile to create and start a configuration for that recording directly: forrecording.undo, choose Debug ‘Replay recording.undo’.Alternatively, from the Run menu, choose Edit Configurations and press the + button at the top left of the Run/Debug Configurations dialog and add a Recording Replay configuration under Undo for Java. Set Recording file to the name of the recording you wish to replay.
Refer to Time travel debugging in IntelliJ for next steps.
Profiling commands¶
The following commands are run offline on a recording.
Method profile¶
If you suspect that a particular method sometimes takes longer than expected to complete you can run a method profiling command on the recording to display a table showing both the bbcount and the elapsed wall-clock time for each call to that method. The command takes the form:
$LR4J_HOME/bin/lr4j_method_profile -k /path/to/keyfile -i /path/to/recording.undo -o /path/to/output.csv -m class.method [-v]
where output.csv is csv version of the output. The -v option produces verbose output including the
console log. The bbcount can then be entered into the log jump panel to go directly to
the start of that method in IntelliJ. For example:
$LR4J_HOME/bin/lr4j_method_profile -k /path/to/keyfile -i /path/to/recording.undo -o /path/to/output.csv -m org.springframework.samples.petclinic.customers.web.OwnerResource.findOwner
┌───────────────────────────────────────────────────────────────────────────┬────────────┬─────────────┬───────┬────────────┐
│location │start time │start bbcount│bbcount│milliseconds│
├───────────────────────────────────────────────────────────────────────────┼────────────┼─────────────┼───────┼────────────┤
│org.springframework.samples.petclinic.customers.web.OwnerResource.findOwner│14:01:00.403│7524030 │77816 │109 │
├───────────────────────────────────────────────────────────────────────────┼────────────┼─────────────┼───────┼────────────┤
│org.springframework.samples.petclinic.customers.web.OwnerResource.findOwner│14:02:09.777│32426403 │22216 │4 │
└───────────────────────────────────────────────────────────────────────────┴────────────┴─────────────┴───────┴────────────┘
Recording profile¶
You can generate a profile showing where the cpu time is spent in a recording by running the following command:
$LR4J_HOME/bin/lr4j_profile -k <keyfile> -i|--input <filename> -s|--samples <num_samples> [-l|--min <min_bbcount>] [--max <max_bbcount>] [-v]
- -k <keyfile>, --key <keyfile>¶
path to the license key file
- -i <filename>, --input <filename>¶
the name of the recording file
- -s <num_samples>, --samples <num_samples>¶
the number of samples to take
- -l <min_bbcount>, --min <min_bbcount>¶
the minimum bbcount to start sampling (default where replay of the program starts)
The command works by dividing the bbcount range (default from where replay starts to the end of the recording) by the given number of samples and obtains the Java stack at that point in the recording. It then outputs a tree summarising the most commonly called methods. There is also a -v option which produces verbose output containing every stack sampled together with its bbcount. The bbcount could then be entered in the Log Jump panel to investigate further. Note that the recording only contains cpu activity so if for instance a large part of the recorded program was waiting on I/O those stacks would not show.
There are many other types of post-failure analysis that can be run on a recording. Contact Undo support for more details.