Loading and saving recordings¶

When suitably licensed, UDB can load and save Undo recordings.

Loading recordings¶

Loading an Undo recording loads the execution history of the program loaded from the recording file, including any debug symbols, so that it is ready to be replayed. It also loads bookmarks created by the same user when previously replaying the recording.

Terminal Visual Studio Code

Load a recording using the uload command in UDB, or by specifying the filename on the UDB command line.

Loading a recording from the command line¶

You can specify an Undo recording when starting UDB. When a recording is passed as a command-line argument to udb, it is automatically loaded. For example:

$ udb recording.undo
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/lib/x86_64-linux-gnu/libm.so.6...
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/usr/lib/debug/.build-id/2d/28b51427b49abcd41dcf611f8f3aa6a2811734.debug...
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/lib/x86_64-linux-gnu/libc.so.6...
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/usr/lib/debug/.build-id/04/01bd8da6edab3e45399d62571357ab12545133.debug...
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/lib64/ld-linux-x86-64.so.2...
Reading symbols from /tmp/undodb.1894129.1714407755.0904398.4bc799f145045bdc/debuggee-1-jyfxzroo/symbol-files/usr/lib/debug/.build-id/42/86bd11475e673b194ee969f5f9e9759695e644.debug...
0x0000558575140080 in _start ()
start 1> continue
Continuing.

Program received signal SIGABRT, Aborted.
Have reached end of recorded history.

The recorded program has exited.
You can use UDB reverse commands to go backwards; see "help udb" for details.

__pthread_kill_implementation (threadid=<optimized out>, signo=signo@entry=6,
    no_tid=no_tid@entry=0) at ./nptl/pthread_kill.c:44
44      ./nptl/pthread_kill.c: No such file or directory.
end 217,026> backtrace
#0  __pthread_kill_implementation (threadid=<optimized out>, signo=signo@entry=6,
    no_tid=no_tid@entry=0) at ./nptl/pthread_kill.c:44
#1  0x00007f39e3362d2f in __pthread_kill_internal (signo=6, threadid=<optimized out>)
    at ./nptl/pthread_kill.c:78
#2  0x00007f39e3313ef2 in __GI_raise (sig=sig@entry=6) at ../sysdeps/posix/raise.c:26
#3  0x00007f39e32fe472 in __GI_abort () at ./stdlib/abort.c:79
#4  0x00005585751403a8 in main () at cache.c:85

uload [-e|-goto-end|-local|-remote] filename¶

Load an Undo recording.

The filename argument names the recording file.

For example:
$ udb
not running> uload recording.undo
0x0000558575140080 in _start ()

The debugged program is at the beginning of recorded history. Start debugging
from here or, to proceed towards the end, use:
    continue - to replay from the beginning
    ugo end  - to jump straight to the end of history
start 1 at-start> continue
Continuing.

Program received signal SIGABRT, Aborted.
Have reached end of recorded history.

The recorded program has exited.
You can use UDB reverse commands to go backwards; see "help udb" for details.

__pthread_kill_implementation (threadid=<optimized out>, signo=signo@entry=6,
    no_tid=no_tid@entry=0) at ./nptl/pthread_kill.c:44
44      ./nptl/pthread_kill.c: No such file or directory.
If a replay service is configured, uload tries to load the recording on the local machine first, falling back to remote replay via the replay service if needed.
-e, -goto-end¶
Jump to the end of execution history immediately after loading. This has the same effect as the ugo end command, but can be substantially faster.
$ udb
not running> uload -e recording.undo
0x0000558575140080 in _start ()

Performing "ugo end" to jump to the end of the recording. Press ^C to
interrupt this and go back to the start.
-local¶

Attempt to load the recording on the local machine only. If this option is specified, UDB does not use replay service, even if it is configured.

-remote¶

Attempt to load the recording using the replay service only.

info recording-version¶

The Undo version used to create the loaded Undo recording.

For example:
end 217,026> info recording-version
7.3.0

Going to the end of execution history after loading¶

By default, UDB starts replaying the recording from the beginning of execution history, but when investigating a crash it is often more convenient to start at the end.

Use the udb --load-goto-end command-line option to start debugging the loaded recording from the end of execution history. This is significantly faster than loading the recording and issuing the ugo end command as separate steps. For example:

$ udb --load-goto-end recording.undo
Reading symbols from /tmp/undodb.1894405.1714407759.986714.e9054707ff776052/debuggee-1-j9h8zsaf/symbol-files/lib/x86_64-linux-gnu/libm.so.6...
Reading symbols from /tmp/undodb.1894405.1714407759.986714.e9054707ff776052/debuggee-1-j9h8zsaf/symbol-files/usr/lib/debug/.build-id/2d/28b51427b49abcd41dcf611f8f3aa6a2811734.debug...
Reading symbols from /usr/lib/debug/.build-id/42/86bd11475e673b194ee969f5f9e9759695e644.debug...
0x0000558575140080 in _start ()

Performing "ugo end" to jump to the end of the recording. Press ^C to
interrupt this and go back to the start.

end 217,026> backtrace
#0  __pthread_kill_implementation (threadid=<optimized out>, signo=signo@entry=6,
    no_tid=no_tid@entry=0) at ./nptl/pthread_kill.c:44
#1  0x00007f39e3362d2f in __pthread_kill_internal (signo=6, threadid=<optimized out>)
    at ./nptl/pthread_kill.c:78
#2  0x00007f39e3313ef2 in __GI_raise (sig=sig@entry=6) at ../sysdeps/posix/raise.c:26
#3  0x00007f39e32fe472 in __GI_abort () at ./stdlib/abort.c:79
#4  0x00005585751403a8 in main () at cache.c:85

This can be configured for all UDB sessions by setting UNDO_load_goto_end to true in the environment.

Replaying on a different CPU¶

Replaying a recording that was created on a different CPU requires that the replay CPU supports all the instructions used by the program when it was recorded. Unless a replay service is configured, UDB refuses to load a recording if these requirements cannot be satisfied, although a warning may be shown instead when loading recordings made with older versions of the Undo Engine.

The info replayability command shows the CPU features required to replay the loaded recording.

info replayability¶

The CPU features required to replay the loaded Undo recording.

The features are reported in the same style as they appear in the flags fields of /proc/cpuinfo. A feature is listed if the program executed an instruction requiring that feature when it was originally recorded. Any hardware which supports all of the listed features can be used to replay this recording.

For example:
end 217,026> info replayability
The CPU features required to replay 'recording.undo' are: avx avx2 bmi1 lm sse
sse2 xsave xsavec.

If you have not yet added a launch configuration to your workspace for replaying an Undo recording, then from the Run menu, select Add Configuration… and then C/C++: (UDB) Replay an Undo recording.

From the View menu, select Run (Ctrl+Shift+D) and from the drop-down menu at the top of the side bar, select (UDB) Replay an Undo recording.

Visual Studio Code pops up a file selection dialog. Select the Undo recording to replay.

Going to the start of execution history after loading¶

By default, UDB starts replaying the recording from the end of execution history. At the end of execution history, a program that called a function such as exit() or abort() will be stopped in library code. In the typical case, when the source code for the library is unavailable, Visual Studio Code hides these frames, as indicated by “Show 2 More Stack Frames” in the CALL STACK window.

Toolbar buttons like Step Over and Reverse Step Over operate on the innermost frame, but this is inconvenient when there is no source code, so in this situation it is often helpful to use the Reverse Step Out button in the toolbar (Ctrl+Shift+F11) to execute backward out of the library functions, until you reach a stack frame for which you have source code.

The end of execution history is usually the most convenient place to start debugging when investigating a failure, but if not, set the "stopAtEntry" field to true in the “(UDB) Replay an Undo recording” configuration. This causes UDB to start replaying from the beginning of execution history, stopping at the beginning of main() if this was captured in the recording.

Replay service¶

The replay service is a web-based service which allows the automatic replay of Undo recordings on a remote machine.

If a replay service is configured, then if a recording cannot be replayed locally, UDB automatically tries to load the recording on a suitable remote machine. A typical case is attempting to replay an ARM64 recording in UDB running on an Intel or AMD x86-64 machine. The automatic behaviour can be modified by specifying the -local or -remote options to the uload command.

Note

This is an early-access feature. The replay service is distributed separately from UDB and requires one or more appropriate machines to run the service and replay recordings.

If you are interested in the replay service, please get in touch with us at support@undo.io.

Backwards compatibility¶

UDB can load Undo recordings that were generated by older versions of the Undo Engine.

The current version of UDB can load recordings generated by any stable version of the Undo Engine from 6.0 onwards.

Support for old versions will be dropped when required in future releases, and this will be announced in the UDB changelog. Generally we aim to preserve support for recordings made by versions that are up to three years old, with older releases supported on a best-effort basis.

UDB cannot typically load recordings that were generated by newer versions of the Undo Engine.

Note

Loading recordings made by newer versions of the Undo Engine may succeed if our internal recording format was not updated in the newer version, but you should avoid relying on this behaviour.

Attempting to load a recording made by a release that is too old or too new will cause an error message to be printed in your UDB session and the load will fail.

Saving recordings¶

Terminal Visual Studio Code

usave [filename]¶

Save execution history as an Undo recording.

The optional filename argument names the recording file. If omitted, a suitable filename is automatically generated.

The recording can be loaded into UDB using the uload command.

Recording File Locking¶

Recordings are locked while they are being written in ordrevent other Undo processes from accessing them before they are mpleted.

Attempts to save a recording to a file path that is already being saved to will fail:

$ live-record -o recording.undo true
live-record: Maximum event log size is 1G.
live-record: Saving to 'recording.undo'...
live-record: Failed to save recording recording.undo: Recording is being written in another process..
live-record: Detaching...

Attempts to load a recording that is being saved to will also fail:

$ udb recording.undo
Failed to load Undo recording.
because: Recording is being written in another process.

New in version 6.5.