# Command Replay

## Overview

The replay tool is an investigation tool shipped in its own separate Docker image. It replays the engine state from a given command index or timestamp, and outputs the data that would have been sent on the websockets feeds at that time. To do this, it scans a given directory, typically the engine persistence directory or the deep storage directory.

## How it Works
It finds a suitable starting point, either from command file 0 or from the first available snapshot in the directory, and replays the commands from that point onwards into a separate instance of the engine.

It outputs the messages that would have been produced by the joined message feed, i.e 
* executions
* transactions
* liquidations
* funding

The replay can be narrowed down to a subset of commands in the available range with --from-index and -to-index options. 
It can also be filtered by account (--account) or by symbol (--symbol). 

## Examples

#### Replay all commands   
```
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current -a --directory persistence
```
Below is a breakdown of the example arguments used to run the replay tool:

- `--rm`  
  ↪ Automatically remove the container and its associated anonymous volumes when it exits

- `-v /path/to/command/files:/app/persistence`  
  ↪ Mounts the local directory `/path/to/command/files` to `/app/persistence` inside the Docker container.  
  This is the location where the replay tool expects to find command files.

- `-it`  
  ↪ Docker run in interactive mode with a pseudo-TTY

- `-e MEMORY=24G`  
  ↪ Set the MEMORY environment variable to 24G

- `replay:current`  
  ↪ Runs the **current version** of the replay image.

- `-a`  
  ↪ Includes **all** available command files for processing.

- `--directory persistence`  
  ↪ Optional. Specifies the subdirectory within `/app` from which command files should be loaded.

- `-o /path/to/output/file`  
  ↪ Directs output to a file at the specified path rather than stdout.

- `-b`  
  ↪ Query and output account positions and balances once index --to-index has been reached.  Requires --to-index and --account to be set, does nothing otherwise.

#### Replay all commands from, to, or within range
```
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --from-index 7245876 --directory persistence
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --to-index 7245924 --directory persistence 
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --from-index 7245876 --to-index 7245924 --directory persistence -o /path/to/output/file
```

#### Filter by account
```
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --account 123 --directory persistence 
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --from-index 7245876 --to-index 7245924 --account 123 --directory persistence -o /path/to/output/file
```

#### Filter by symbol
```
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --symbol ETHUSDT --directory persistence
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --from-index 7245876 --to-index 7245924 --symbol ETHUSDT --directory persistence
docker run --rm -v /path/to/command/files:/app/persistence -it -e MEMORY=24G replay:current --from-index 7245876 --to-index 7245924 --symbol ETHUSDT --account 123 --directory persistence -o /path/to/output/file
```