RETRACE

RETRACE is a native Linux process recorder and fault-injection tool. Its goal is to show important process-boundary behavior and then recreate selected failure conditions deliberately.

A program failed under unusual conditions. What happened, and can those conditions be recreated?

Status

RETRACE is pre-alpha but has a working process-recording and inspection slice:

• retrace run launches a command and preserves its arguments;
• run --working-directory PATH selects and records the target directory;
• each target leads a process group, and received SIGINT/SIGTERM signals are forwarded to that group and recorded;
• normal exits and signal termination are returned to the caller;
• launch failure is distinguished from a target that exits with status 127;
• stdout and stderr are collected concurrently through separate pipes and forwarded to the caller;
• run --output TRACE writes an exclusive, user-only v1.0 trace containing command metadata, lifecycle events, and captured stream chunks;
• retrace inspect TRACE renders a bounded, escaped timeline, including valid unknown event types;
• retrace validate TRACE checks the v1.0 structure without loading the whole event stream into memory; and
• each ordinary run locates and loads libretrace_runtime.so with LD_PRELOAD, preserves caller preload entries, validates its bounded Unix-domain channel, and records runtime.handshake; --no-runtime disables this path;
• the loaded runtime interposes open, open64, openat, openat64, and close, and each observed call becomes a file.open or file.close trace event carrying its path, descriptor, result, errno, and duration;
• operations the bounded runtime channel dropped are counted and reported, so an incomplete recording is never presented as a complete one; and
• dependency-free tests exercise the CLI, process and trace layers, plus C stream, file, and runtime fixtures.

Socket and read/write instrumentation, time limits, trace export, and fault injection are not implemented yet. Static, setuid, or otherwise loader-restricted targets cannot be instrumented; RETRACE reports a missing required handshake after preserving their observed lifecycle evidence. A successful validation means that the bytes are structurally valid v1.0; because v1.0 has no footer or checksum, it does not prove that a run was finalized or that its contents are authentic.

RETRACE is open source under the MIT License.

Product direction

The current runner can execute a target:

./build/dev/bin/retrace run -- /bin/echo "hello from RETRACE"
./build/dev/bin/retrace run -- python3 -c 'print("hello from Python")'
./build/dev/bin/retrace run --output /tmp/example.rtc -- /bin/echo recorded
./build/dev/bin/retrace run --working-directory /tmp -- /bin/pwd
./build/dev/bin/retrace run --no-runtime -- /bin/echo recorder-only

Recorded traces can be inspected or structurally validated:

./build/dev/bin/retrace inspect /tmp/example.rtc
./build/dev/bin/retrace validate /tmp/example.rtc

The v0.1 process-recorder slice is implemented. The v0.2 work now includes a standalone C17 library, versioned handshake, a supervisor-owned channel that automatically loads the runtime into supported dynamic targets, and recorded file operations observed inside the target:

./build/dev/bin/retrace run --output /tmp/files.rtc -- /bin/cat /etc/hostname
./build/dev/bin/retrace inspect /tmp/files.rtc

       0.594 ms  file.open    pid=68278 tid=68278 fd=3 path="/etc/hostname" ...
       0.598 ms  file.close   pid=68278 tid=68278 fd=3 ...

Socket and read/write operations are the remaining v0.2 slice; v0.3 will control them with bounded fault rules:

# Planned for v0.3; not implemented yet.
retrace run \
  --fail 'open:/tmp/cache/*:EACCES' \
  --delay 'connect:127.0.0.1:5432:500ms' \
  -- ./example-server

RETRACE will not claim deterministic replay, complete syscall visibility, or debugger-level control. When recording and fault injection ship, it will recreate selected conditions and record only what it actually observed or injected.

Build and run

Requirements:

• Linux
• CMake 3.25 or newer
• Ninja
• A C17 and C++20 compiler (GCC or Clang)

cmake --preset dev
cmake --build --preset dev
ctest --preset dev
./build/dev/bin/retrace version
./build/dev/bin/retrace run -- /bin/echo hello

No third-party runtime or test dependencies are used at this stage.

Documentation

• Documentation map
• Architecture
• Product goals and scope
• Development design
• CLI design
• Trace format
• Recorder examples
• Fault rules
• Security model
• Roadmap
• v0.1 release checklist
• C and C++ learning guide
• Contributing

Safety warning

Trace data may contain command arguments, working directories, the paths of files the target opened, standard output, and standard error. Any of those can contain secrets. Recording currently requires an explicit --output path; review every trace before sharing it. See docs/security.md for the full safety model.

Scope

RETRACE is Linux-first and does not initially aim to provide kernel modules, eBPF instrumentation, source-level debugging, profiling, container isolation, distributed tracing, or multi-host coordination. Small useful releases take priority over speculative infrastructure.

License

RETRACE is available under the MIT License.