Using the LiveRecorder tool¶
Depending on your license, LiveRecorder can be provided as a command-line tool
called live-record that allows you to record the execution of a
process on your Linux command line. This tool can be used a bit like the
strace
tool on Linux, except that it makes LiveRecorder recordings instead
of printing system calls and signals.
The tool will be installed to your preferred location when you run make
install
, and usage notes are printed if you run live-record with
the --help
option.
Usage example¶
The LiveRecorder tool can be used both to launch a new process and to attach to an existing one.
You can launch a program with the path path/to/program
with program arguments
arg1
, arg2
and arg3
, with the following command:
$> live-record path/to/program arg1 arg2 arg3
When your application terminates, live-record will write a recording
to a file whose name is printed to your terminal. If you wish to specify a
recording filename, use the --recording-file
option as follows:
$> live-record --recording-file my_recording.undo path/to/program arg1 arg2 arg3
Ordinarily recordings are always written when your application terminates. You
can use the --save-on
option to fine-tune the circumstances under
which the tool saves a recording. For example, if you want a recording to be
saved only if the application terminates abnormally in some way, either due to
being terminated by a signal or returning a non-zero exit status, use the
error
value for the --save-on
option:
$> live-record --save-on error --recording-file my_recording.undo path/to/program arg1 arg2 arg3
Alternatively, if you only want a recording file if your application terminates
due to a signal, use the signal
value for the --save-on
option.
You can attach to an already running process by using the --pid
option. For example, to attach to process 1234:
$> live-record --pid 1234
All options apply to both the launch and attach cases.
Options¶
- -h, --help¶
Show help summary.
- -v, --version¶
Print version information and then exit.
- -q, --quiet¶
Suppress output from the tool on standard streams, unless an error occurs.
- -p PID, --pid PID¶
Attach to the process
PID
and start recording it.
- -o FILENAME, --recording-file FILENAME¶
Save the LiveRecorder recording to
FILENAME
.
- --recording-dir DIRNAME¶
Save the LiveRecorder recording in the directory
DIRNAME
. This is ignored if the-o
or--recording-file
option is given.
- --save-on CIRCUMSTANCE[,CIRCUMSTANCE,...]¶
Save only in the given circumstances, which must be one or more of:
always
Always save a recording. This is the default behaviour if the
--save-on
option is not given.detach
Save when live-record detaches from the program due to receiving
SIGUSR1
orSIGINT
.error
Shorthand for
failure,signal,unsupported
.failure
Save when the program exits with a non-zero status.
signal
Save when the program exits due to an unhandled signal.
success
Save when the program exits with a zero status.
unsupported
Save when the program does something that is not supported by live-record.
- --max-event-log-size SIZE[K|M|G]¶
Set the maximum event log size.
- --thread-fuzzing¶
Enable Thread Fuzzing, which varies the scheduling of threads to attempt to provoke race conditions.
- --tmpdir-root DIRNAME¶
Set the directory used by live-record for its temporary files.
Signals¶
live-record has special handling for the following signals, if they are delivered to the LiveRecorder controller process:
SIGINT
In the attach case, this signal causes live-record to detach from the target process, saving a recording if the
--save-on
option includesdetach
. In the launch case, this signal is delivered to the target process, and if it causes the target process to exit then live-record saves a recording if the--save-on
option includessignal
.SIGUSR1
live-record detaches from the target process, saving a recording if the
--save-on
option includesdetach
.SIGHUP
This signal is delivered to the target process, and if it causes the target process to exit then live-record saves a recording if the
--save-on
option includessignal
.SIGTERM
live-record exits cleanly without saving a recording, in both the attach and launch cases. The
--save-on
option is ignored.
In the attach case, the LiveRecorder controller process is the instance of
live-record, but in the launch case it is a daemon process that can
be found by its name undo-lr-PID
, where PID
is the id of the target
process, for example, by using pgrep.
Warning
The SIGSTOP
signal is used internally by LiveRecorder and cannot
be reliably delivered to the target process. If you need to temporarily stop
the target process while it is being recorded you can instead use the
SIGTSTP
signal.
Notes¶
As with tools like
strace
(but unlike GDB), the path to the executable you wish to record must either be on yourPATH
, or must be fully qualified.In the launch case, live-record forks a daemon process to do the recording, and execs the target process. This means that the target process is a direct child of the shell which ran live-record.
The exit code of live-record is the exit code of the recorded program, unless live-record detaches on a signal as described above.
Your customer UID will be embedded in each recording created by live-record, and these recordings will only be loadable by a correspondingly licensed udb.
Limitations¶
The limitations of all tools built around the Undo Engine apply also to the live-record tool. See System requirements for details. The following limitations apply to live-record only:
live-record does not always report errors very well. If live-record fails and does not appear to produce any useful output, please contact us at support@undo.io.