Querying recordings¶

After using LiveRecorder for some time, you may find that you’ve built up a library of Undo recordings which you need to query in order to find a recording of interest, to understand the context in which a recording was made, or to statistically analyze aspects of the behavior of the recorded program.

To answer these questions, the undo recording-summary and undo recording-json programs are available to extract information from Undo recordings.

undo recording-summary¶

undo recording-summary presents a summary of an Undo recording in a human-readable format.

It is useful for quickly checking the recording’s contents, but is not suitable for automatic processing and the output format may change in future. If parsing of the output is necessary, please refer to undo recording-json for a structured format.

Usage synopsis¶

undo recording-summary [OPTIONS ...] RECORDING

Options¶

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

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

Output format¶

The output of the undo recording-summary program is split into three sections:

Program¶

Recorded program

The name of the recorded program.

Program termination reason

The reason the program terminated.

Recorded time range (UTC)

The start and end time of the recording in UTC.

Recorded time duration

The total duration of the recording.

Bbcount range

The start and end bbcount of the recording, as well as whether the event log was rotated. See Event log rotation for more details.

Architecture

The architecture of the recorded program.

Minimum memory requirement

The minimum memory required to replay the recording, with and without overcommit. Overcommit is a kernel setting that allows the allocation of memory to be deferred until it is actually needed, which can reduce the memory footprint of a program. For more information, see overcommit accounting in the Linux kernel documentation.

Recording platform¶

Created on system

Information about the system where the recording was created, including the operating system, hostname, kernel version, and architecture. This is similar to the output of the uname program.

Undo Engine version

The version of the Undo Engine used to create the recording, along with the recording format version.

License UID

The unique identifier of the license used to create the recording.

File size¶

Recording file

The total size of the recording file.

Event data

The total size and overall proportion of the event log sections of the recording, which contain a log of all non-deterministic behavior exhibited by the recorded program.

Executable and debug files

The size and overall proportion of the section containing the executable and debug information files.

Program state

The total size and overall proportion of the sections of the recording containing program state, which include the memory of the recorded program at the start of recorded history, as well as an optimised representation for each snapshot.

System information

The total size and overall proportion of the sections of the recording containing information about the system on which the recording was made.

Example usage¶

$ undo recording-summary recording.undo
Program
  Recorded program            gzip
  Program termination reason  Program terminated with exit code 0
  Recorded time range (UTC)   2025-05-14 16:47:03.637543 -> 2025-05-14 16:47:06.287490
  Recorded time duration      0:00:02.649947
  Bbcount range               174,586,265 -> 821,653,570 (rotated)
  Architecture                x64
  Minimum memory requirement  10.58MB (112.84MB without overcommit)

Recording platform
  Created on system    Linux, example-machine, 6.9.12-amd64, #1 SMP PREEMPT_DYNAMIC Debian
                       6.9.12-1 (2024-07-27)
  Undo Engine version  8.3.0 (recording format: 82)
  License UID          0123456789abcdef0123456789abcdef0123456789abcdef01234567

File size
                                 Size    Proportion
  Recording file              68.78MB
  Event data                  59.16MB        86.02%
  Executable and debug files   5.75MB         8.36%
  Program state                3.82MB         5.56%
  System information          38.86KB         0.06%

undo recording-json¶

undo recording-json outputs a description of the contents of an Undo recording in JSON (JavaScript Object Notation). The output is not intended for human inspection, but should be piped into a suitable program for further processing, for example, jq, which is convenient for simple queries on the command line, or python, using the json module.

Note

jq may be installed using your distribution’s package manager.

On Fedora and Red Hat, using Extra Packages for Enterprise Linux (EPEL):

$ sudo yum install epel-release
$ sudo yum install jq

On Ubuntu:

$ sudo apt install jq

Usage synopsis¶

undo recording-json [OPTIONS ...] RECORDING

Options¶

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

--sections SECTIONS, -s SECTIONS¶

Output only the specified sections of the recording, where SECTIONS is a string containing one or more of these letters:

Letter	Section
`b`	blocks
`c`	cpuinfo and vDSO entry points
`d`	debuggee and replayable information
`e`	events and synthetic events
`f`	files
`h`	header and sysinfo
`l`	layout summaries
`m`	maps
`n`	notes

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

Output format¶

The output is a single JSON object with the following top-level keys.

"blocks"

List of blocks making up the recording file.

"config"

Product configuration parameters captured when the recording was saved. These are not needed for replaying the recording, but may be useful for understanding the context of the recording, or diagnosing problems in UDB itself.

"cpuinfo"

Object describing features of the CPU on which the recording was made that need to be queried when replaying the recording. (Contrast the "sysinfo" section, which contains general information about the recording machine.)

"debuggee"

General description of the recorded program.

"files"

List of files embedded in the recording that contain symbols and other debugging information needed when replaying the recording.

"header"

General information about the recording, including its format version, the Undo release that created it, the date and time that it was recorded, its compression scheme, and so on.

"notes"

List of notes added to the recording. Notes are key-value pairs that contain arbitrary data not required to replay the recording.

"replay_features"

Modifications to features when the program was recorded.

"replayables"

List of objects describing the “replayables”, data structures describing the recorded program at a particular point in execution history. There is always at least one replayable, describing the recorded program at the start of execution history. This object has keys:

"events"

List of events describing non-deterministic behavior of the recorded program.

"layouts"

Memory layout summaries used to ensure that the Undo Engine’s internal data structures do not collide with addresses used by the recorded program.

"maps"

Memory maps in the recorded program.

"replayable"

Information about the replayable.

"synthetic"

List of synthetic events (that is, not corresponding to events that happened when the program was recorded) that ensure that when the recording is replayed, threads and memory are the same as when the program was recorded.

"sysinfo"

Files, environment variables, logs, and other data captured when the recording was saved. These are not needed for replaying the recording, but may be useful for understanding the context of the recording, or diagnosing problems in UDB itself. (Contrast the "cpuinfo" and "files" sections, which contain information that is needed when replaying the recording.)

"vdso"

List of vDSO entry points in the recorded program.

Example queries¶

Using jq¶

Which Undo version made a recording?

$ undo recording-json -s h recording.undo | jq -r .header.undo_version
7.2.0

On which host was a recording made?

$ undo recording-json -s h recording.undo | jq -r .header.uname_nodename
test-x64-ykjfxtcr.example.com

Which instruction set extensions were used by the recorded program?

$ undo recording-json -s h recording.undo | jq -r .header.isaexts
avx avx2 bmi1 lm sse sse2 xsave xsavec

Pretty-print the vDSO memory map.

$ undo recording-json recording.undo | jq '.replayables[0].maps[] | select(.path=="[vdso]")'
{
  "begin": 140731969982464,
  "end": 140731969986560,
  "sparse": false,
  "path": "[vdso]",
  "read": true,
  "write": false,
  "execute": true,
  "shared": false,
  "grows_down": false,
  "inode": 0,
  "dev_major": 0,
  "dev_minor": 0,
  "is_shmat": false,
  "offset": 0,
  "pkey": 0
}

Print all events for all the replayables, one per line using the -c (compact) output format.

$ undo recording-json -s e recording.undo | jq -c .replayables[].events[] | tail -5
{"type":"pread64","size":80,"bbcount":770084,"syscall":17,"result":0}
{"type":"pread64","size":80,"bbcount":770091,"syscall":17,"result":0}
{"type":"close","size":72,"bbcount":771087,"syscall":3,"result":0}
{"type":"munmap","size":128,"bbcount":771114,"syscall":11,"result":0}
{"type":"write","size":80,"bbcount":771303,"syscall":1,"result":91}

Using python¶

What was the current directory when a recording was made?

import json, sys
for line in json.load(sys.stdin)["sysinfo"]["Child Environment"].splitlines():
    if line.startswith("PWD="):
        print(line.removeprefix("PWD="))

$ undo recording-json -s h recording.undo | python get_original_pwd.py
/testfarm/jobs/ykjfxtcr/workspace

What are the most common types of event in a recording?

import collections, json, sys
replayables = json.load(sys.stdin)["replayables"]
counter = collections.Counter(e["type"] for r in replayables for e in r["events"])
print(counter.most_common(4))

$ undo recording-json -s e recording.undo | python most_common_events.py
[('XSAVE', 1236), ('write', 151), ('open', 57), ('mmap', 52)]

Cautions¶

The exact format of the output is subject to change without notice in new UDB releases: we do not promise to maintain backwards compatibility. Changes will be noted in the UDB changelog.
The output includes addresses in the recorded program, which can be arbitrary 64-bit numbers. Some JSON-processing tools, notably jq, cannot represent integers larger than 2⁵³ exactly, rounding them to the nearest double-precision floating-point number instead. However, Python is safe in this respect.