Using the LiveRecorder tool¶

The live-record command-line tool runs a program, or attaches to a running process, and optionally captures an Undo recording of the execution history of that program.

To launch a program and record its execution, pass the program and its arguments on the live-record command line, for example:

$ live-record path/to/program arg1 arg2 arg3

When the program exits, live-record writes its execution history to an Undo recording, and reports the filename of the recording. To specify a recording filename, use the --recording-file option, for example:

$ live-record --recording-file recording.undo path/to/program arg1 arg2 arg3

By default, live-record always writes an Undo recording when the program exits. Use the --save-on option to specify the circumstances under which the tool saves a recording. For example, to save a recording only if the program exits abnormally (that is, it is terminated by a signal, or exits with a non-zero exit status), use --save-on error:

$ live-record --save-on error --recording-file recording.undo path/to/program arg1 arg2 arg3

To attach to a running process, use the --pid option. For example, to attach to process 1234:

$ live-record --pid 1234

Options¶

--disable-aslr¶: Disable address-space-layout randomization (ASLR) in the recorded program.

Note

This only works when launching the program to be recorded. When using live-record to attach to a running program, you must disable ASLR when starting the program, for example, by using setarch with the --addr-no-randomize option. See the setarch manual for details.

--help, -h¶: Show help summary and exit.

--list, -l¶: List all currently running LiveRecorder sessions and exit. This includes sessions for all users, and sessions started by either the live-record tool or the LiveRecorder API.

--max-event-log-size SIZE[K|M|G]¶: Set the maximum event log size.

--pid PID, -p PID¶: Attach to the process PID and start recording it.

--quiet, -q¶: Suppress all output from live-record, unless an error occurs.

--recording-dir DIRNAME¶: Save the Undo recording in the directory DIRNAME. This is ignored if the --recording-file option is also given.

--recording-file FILENAME, -o FILENAME¶: Save the Undo recording to FILENAME.

--retry-for DURATION¶: Run the program repeatedly until either DURATION has passed or the circumstances specified by the --save-on option have occurred and a recording has been saved, whichever happens first. DURATION must be a number followed by a unit of time: for example, 60s to repeat for up to 60 seconds. The unit may be s (seconds), min (minutes) or h (hours). In this mode, the exit status is zero if a recording was saved, or non-zero if not.

--save-on CIRCUMSTANCE[,CIRCUMSTANCE,...]¶

Save the recording only in the specified circumstances.

The most useful circumstances are:

`always`	Always save a recording. This is the default when no `--save-on` option is specified.
`error`	Save a recording when something goes wrong, but not if the program exits successfully or if live-record is detached. This is often used to record automated tests. It is equivalent to `exit-non-zero,exit-signal,unsupported`.

The individual circumstances which can also be specified are:

`detach`	Save when live-record receives `SIGINT` and detaches from the program. (Note that receiving `SIGUSR1` also causes live-record to detach but a recording is always saved in that case.)
`exit-non-zero`	Save when the program exits with a non-zero exit status.
`exit-signal`	Save when the program exits due to an unhandled signal.
`exit-zero`	Save when the program exits with a zero exit status.
`unsupported`	Save when the program does something that is not supported by live-record.

--record-on CIRCUMSTANCE¶

Start recording only in the given circumstance. This option is not supported when attaching to an existing process. CIRCUMSTANCE must be one of:

`entry`	Start recording at the program entry point. This is the default behaviour.
`immediate`	Start recording at the very first instruction of the new process. Use this to record the behaviour of the dynamic linker before the entry point is reached.
`symbol:SYMBOL`	Start recording when execution reaches the address denoted by `SYMBOL`, for example, `symbol:main`.
`program:PATTERN`	Watch the process and all its descendants. Any process whose name matches `PATTERN` will be recorded from its entry point. `PATTERN` must be an extended shell glob pattern, for example, `?(prog1\|prog2*)`. See the `glob()` manual, the documentation for `FNM_EXTMATCH` in the `fnmatch()` manual, and Limitations below.

--thread-fuzzing¶: Enable Thread Fuzzing, which varies the scheduling of threads to increase the frequency with which concurrency bugs are reproduced.

--tmpdir-root DIRNAME¶: Set the directory used by live-record for its temporary files.

--verbose¶: Print extra information. At startup, print instructions for controlling live-record with signals. When saving, print the recording size, the time period covered by the recording, and whether the event log has rotated, meaning that the initial portion of execution history has been discarded.

--version, -v¶: Print version information and exit.

Controlling live-record with signals¶

live-record can be controlled by sending one of the following signals to the controller process. The --verbose option tells live-record to print instructions for using these signals, or you can find the controller process by running live-record --list.

SIGINT

This causes live-record to detach from the target process, leaving it running. If the value of the --save-on option includes detach, it saves a recording.

In the attach case, you can signal the controller process with SIGINT by typing control-C in the terminal.

SIGUSR1

This causes live-record to unconditionally save a recording and then detach from the target process, leaving it running. This ignores the value of the --save-on option.

SIGTERM

This causes live-record to detach from the target process without saving a recording, leaving it running. This ignores the value of the --save-on option.

Signalling the target process¶

Warning

If the target program receives SIGKILL, a recording cannot be saved, since SIGKILL cannot be caught.

Warning

The SIGSTOP signal is used internally by LiveRecorder and cannot be reliably delivered to the target process. To temporarily stop the process while it is being recorded, use the SIGTSTP signal.

Notes¶

The program to be recorded is located via the PATH environment variable if its name does not contain /.
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, or the --retry-for option was used.
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 using the Undo Engine apply also to live-record. See System requirements for details. The following limitations apply to live-record only:

The --record-on program option uses a library loaded by setting the LD_PRELOAD environment variable, and configured by the UNDO_autorecord_args, UNDO_autorecord_exe and UNDO_autorecord_glob environment variables. If a program unsets any of these variables, its descendants will not be recorded.
The --record-on program option works by intercepting calls to the exec() family of functions in the standard C library (execl(), execv(), and so on). A consequence of this implementation is that processes started by directly invoking the execve system call are not matched and so not recorded.
live-record generates little output (or none if the --quiet option is used) so that it can be used to record programs whose output is depended on. This means that it does not always report errors very well. If live-record fails and does not appear to produce any useful output, please contact Undo Support.