Skip to content

quickstart.md

Latest commit

 

History

History
55 lines (37 loc) · 1.92 KB

quickstart.md

File metadata and controls

55 lines (37 loc) · 1.92 KB

Quickstart

Debug a flaky script end-to-end: record, inspect the timeline, and rewind to the exact moment it broke.

Prerequisites

  • Docker: The recommended build method uses Docker to provide a consistent environment with all dependencies included.
  • Runtime Privileges (Linux): The core recording feature requires sudo privileges to attach the eBPF probes to the kernel.
  • Platform Support: The high-performance eBPF monitoring is Linux-specific. The tool provides a fallback for macOS and Windows with different performance characteristics.

1) Build DiffKeeper (or install via the GitHub Action)

The recommended way to build DiffKeeper is with Docker, which avoids needing to install any local dependencies.

# Build the 'diffkeeper' binary into the ./bin directory
make build-dockerized

The final binary will be located at bin/diffkeeper.

Alternative: Local Builds If you prefer to build locally, you will need Go 1.23+, clang, and bpftool. You can then run make build.

CI users can skip this and reference uses: saworbit/diffkeeper@v1 in a workflow.

2) Run the Flaky Demo Under DiffKeeper

The repo ships with a tiny flaky test that silently corrupts status.log after 2 seconds.

./diffkeeper record --state-dir=./trace -- go run ./demo/flaky-ci-test

The process exits with a failure after a few seconds (expected).

3) Read the Timeline (no more guesswork)

./diffkeeper timeline --state-dir=./trace
[00m:00s] WRITE    status.log (13B)
[00m:01s] WRITE    db.lock (6B)
[00m:02s] WRITE    status.log (22B)   <-- corruption point

Now you know the precise timestamp to rewind to.

4) Export the Crash Site

./diffkeeper export --state-dir=./trace --out=./restored --time="2s"
cat ./restored/status.log
# Output: ERROR: Connection Lost

You have successfully captured the filesystem history, located the offending write, and restored the exact failing state.