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

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 parameter 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 parameter 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 --save-on error:

$> 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 --save-on signal. The usage notes printed by --help provide more details about the --save-on parameter.

You can attach to an already running process by using the --pid parameter. For example, if you want to attach to a process that is already running with pid 1234:

$> live-record --pid 1234

You can use all the optional parameters discussed above for both the launch and attach cases.

Signals

The LiveRecorder tool handles the following signals in a specific way:

SIGINT

In the attach case it causes the LiveRecorder tool to detach from the target process, saving a recording in case no --save-on option was given or if --save-on detach was specified. In the launch case it is ignored: this signal is going to be delivered to the target process, and if it causes the target process to exit then LiveRecorder will handle that, saving the recording in case no --save-on option was given or if --save-on signal was specified.

SIGUSR1

The LiveRecorder tool will detach from the target process, saving a recording in case no --save-on option was given or if --save-on detach was specified.

SIGHUP

It is ignored: this signal is going to be delivered to the target process, and if it causes the target process to exit then LiveRecorder will handle that, saving the recording in case no --save-on option was given or if --save-on signal was specified.

SIGTERM

The LiveRecorder tool will exit cleanly without saving any recording, both in the attach and launch cases. Any --save-on option is ignored.

Notes

  • As mentioned above, you must select the correct live-record binary for the executable you wish to record.

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

  • The LiveRecorder tool runs as a grandchild of the target process in the launch case. For example, if you record a process and want it to go in the background:

    $> live-record path/to/program arg1 arg2 arg3 &
    [1] 1234
    

    Then 1234 is the PID of the target process, not of live-record. This reduces the visible effect of live-record, keeping the target process a direct child of the calling process.

  • The exit code from live-record command-line will be the exit code from the recorded executable, unless the --no-return-debuggee-exit-code parameter is passed to live-record. This does not affect the behaviour of --save-on in that if your application has a non-zero exit status and you have requested that recordings are saved in that circumstance then a recording will be written, even if that exit status is not returned.

  • Your customer UID will be embedded in each recording that live-record creates, 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. 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 http://support.undo.io