A Tour of Replay for New Contributors

Getting Started

Before diving into the technical nitty-gritty, we recommend all newcomers getting familiar with Replay and its ability to help developers analyze execution behavior first. One way to do that is through the Replays in our curated Replayable list (src: github.com/replayio/replayable).

Replay Basics

We wrote some blog posts outlining how Replay works internally, covering the basics of how we record OS syscalls, use โ€œeffective determinismโ€ to minimize the data needed, and turn browser processes in the cloud into a public API that can be used to introspect a programโ€™s behavior:

Replay Architecture

Replay is a vast and complex system with many moving parts. The following is a largely simplified overview of how it works:
Image without caption


  • Replay Client [Open Source]
    • The main Replay client that users are familiar with is the DevTools, which is the web app at https://app.replay.io/ (src: ). It allows you to select a previously recorded Replay and then replay it in our web-based Replay GUI.
    • The Replay CLI (src: ) allows you to programmatically interact with a Replay.
  • Test Suites [Open Source]
    • Users can use our cypress and other runtime wrappers to easily record and replay entire test suites (src: ).
  • Runtime [Open Source]
    • The most prominent runtime is our โ€œReplay Browserโ€ based on Firefox (src: ), available in our Downloads section.
    • We are currently working on a Chromium variant (src: ), and hope to provide even more runtimes in the future, including Node (src: ).
    • NOTE: Even though these repos are open source, their open source development is currently not possible, since replaying custom build recordings requires non open source tools. We are looking forward to remedy that situation when we have the capacity to do so!
  • Driver and Linker [Closed Source ๐Ÿค]
    • The driver and linker are wrappers around the runtime (and actually very different in functionality from their namesakes). Their crucial roles are explained in this blog article.
  • Backend, Dispatcher, Controller [Closed Source ๐Ÿค]
    • TODO

Runtime Deep Dive

Thereโ€™s also a recent set of posts talking about the โ€œeffective determinismโ€ aspect in more detail, including how we can replay the full browser behavior with a relatively small recorded set of input data, and how we investigate โ€œruntime mismatchโ€ errors internally:
For some additional details, see these docs pages:
๐Ÿ”„Our approach for source maps (1)๐ŸƒHow programmatic recordings work (1)

The Replay Protocol

For examples of how the Replay Protocol API is used, see the actual Replay DevTools client repo, the Replay Protocol API Examples repo, and the Protocol API docs