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¶

--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 live-record output on standard streams, unless an error occurs.

--recording-dir DIRNAME¶: Save the LiveRecorder recording in the directory DIRNAME. This is ignored if the --recording-file or -o option is given.

--recording-file FILENAME, -o FILENAME¶: Save the LiveRecorder 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,...]¶

Only save the recording if live-record stops recording for one of the specified circumstances, otherwise discard it.

The circumstances most commonly used are:

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

The individual circumstances which can also be specified are:

`detach`	Save when live-record is detached from the program with `control-C` or `SIGINT`. (Note that `SIGUSR1` causes a detach but always saves.)
`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` is a shell glob pattern with extended patterns: for example `?(prog1\|prog2*)`. See the `glob manual_` and `FNM_EXTMATCH` in the fnmatch manual for more details. See Limitations below.

--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.

--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 advise if the event log has rotated, meaning that the older part of recorded history has been discarded.

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

Detaching¶

When live-record exits, if it attached to an existing process, it will leave that process running. This can usually be done by pressing control-C.

Note

Note that if live-record is run from a terminal and launches a new process, control-C will be sent to that process, not to live-record. That usually causes that program to exit (usually causing live-record to save a recording). But it is possible to stop recording and leave the program running by sending a SIGINT signal to the live-record controller process.

Controlling live-record with Signals¶

live-record can be told to stop or to save a recording by sending a signal to the controller process.

Note

The controller process’s process ID is displayed if live-record was specified with the --verbose option.

It can also be identified by its process name, for instance by using pgrep. In the attach case, the controller process is the instance of live-record. In the launch case it is a separate daemon process with the name undo-lr-PID, where PID is the process id of the target process.

SIGINT: This causes live-record to detach from the recorded process the same as if it received control-C in a terminal. It leaves the process running. It will first save a recording (unless a more restrictive --save-on option had been specified on its command line).
SIGUSR1: This causes live-record to unconditionally save a recording, ignoring any --save-on option. It then detaches, leaving the recorded process running.
SIGTERM: This causes live-record to detach from the recorded process and exit without saving a recording. It leaves that process running. This ignores any --save-on options.

Signals to the Recorded Program¶

Warning

If the recorded program is killed with kill a recording will usually be saved showing the program exited due to a SIGTERM signal. However note that if the program is stopped with SIGKILL, for instance from kill -9, a recording can’t be saved. If the recording is needed, it can be saved first by sending SIGUSR or SIGINT to live-record.

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 your PATH, 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:

The --record-on program option uses a library loaded via setting the LD_PRELOAD environment variable, and configured via the variables UNDO_autorecord_args, UNDO_autorecord_exe and UNDO_autorecord_glob. If a program unsets any of these variables, 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 exec syscall are not matched and so not recorded.
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.