Using the Live Recorder tool

Depending on your license, Live Recorder 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 Undo 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

To record a program with the path path/to/program with program arguments arg1, arg2 and arg3, you can run 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.

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

Limitations

The limitations of all tools built around the Undo Engine apply also to the live-record tool. The following limitations also 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