Spanner-like Read-Only Protocols and Anomaly Checker

Building on the Spanner-RSS implementation, this repository contains implementations of Spanner-like read-only transaction protocols and offline tools for analyzing their execution traces. The system records committed read-write (RW) and read-only (RO) transactions, and the anomaly checker builds a transaction dependency graph, adds definite real-time ordering under a configurable clock-error bound, and finds and analyzes cycles in the resulting graph.

Running Experiments and Collecting Traces

The supplied configs under experiments/configs are templates for an SSH-accessible Linux cluster. They retain the workload and placement settings used for the included results but contain cluster-specific host aliases (X2--X7), network interfaces, CPU pinning, and filesystem paths that must be adapted.

The experiment harness kills existing benchmark/server processes, changes CPU governors and kernel network settings, drops caches, and configures tc rules. Run it only on dedicated machines with passwordless, privileged SSH access.

Requirements

• CMake 3.10 or newer and a C++14 compiler
• Protocol Buffers, OpenSSL, and libevent development packages
• Python 3, NumPy, and gnuplot
• An SSH-accessible Linux cluster

The system and experiment harness were evaluated with CMake 3.10.2, GCC/G++ 7.5.0, Python 3.6.9, and gnuplot 5.2.

Build and Run

1. Clone the repository with its submodules:

   git clone --recurse-submodules <repo-url>
   cd <repo-directory>

2. Install the build and experiment dependencies (Ubuntu package names):

   sudo apt update
   sudo apt install -y build-essential cmake libevent-dev libprotobuf-dev \
     libssl-dev protobuf-compiler python3-numpy gnuplot openssh-client

   Cluster nodes additionally need tc (from iproute2), taskset, lsof, and standard sysctl/procfs utilities.

3. Build the benchmark and server:

   mkdir -p src/build
   cd src/build
   cmake ..
   make -j8
   cd ../..

4. Choose a config under experiments/configs. Replace its /path/to/... placeholders and update server_names, shards, clients, server_regions, net_ifaces, ssh_user, and CPU-pinning fields for the target cluster.

5. Run the selected experiment family:

   python3 experiments/run_multiple_experiments.py \
     experiments/configs/<config>.json

The runner creates timestamped directories below base_local_exp_directory. Each concrete run contains its expanded config, an out/stats.json performance summary, and client logs containing #RWC and #ROC trace records.

Analyzing Traces

The current analysis scripts require Python 3.8 or newer.

Anomaly Analysis

For automatic discovery, each concrete experiment must contain a config JSON next to its out directory:

<results_dir>/
  <experiment>/
    <config>.json
    out/
      <client>/<client>-<process>-stdout-0.log

Run the checker over all concrete experiments below a results directory:

python3 checker/analyze_anomalies.py <results_dir> --workers 16

Other supported invocations are:

# Analyze selected protocol models
python3 checker/analyze_anomalies.py \
  <results_dir> --models rss,pos,ser --workers 16

# Include shortest-hop witness paths
python3 checker/analyze_anomalies.py \
  <results_dir> --workers 16 --include-witness

# Analyze one concrete experiment
python3 checker/analyze_anomalies.py \
  <config_file> <out_dir> --workers 16

Options:

• --clock-err N: clock-error bound in trace timestamp units (default: 100)
• --workers N: worker processes for parallel analyses (default: 1)
• --models LIST: comma-separated protocol filter
• --include-witness: include shortest-hop witness-path analysis

Performance Analysis

The performance analyzer accepts either a results tree or one out/stats.json file:

python3 checker/analyze_performance.py <results_dir>
python3 checker/analyze_performance.py <results_dir> --models rss,pos,ser
python3 checker/analyze_performance.py <path/to/out/stats.json>

Included Outputs

Precomputed analyzer outputs for the five supplied experiment configs are available under checker/output:

• anomalies_family.txt
• anomalies_ss.txt
• performance.txt

Raw execution traces are not included because of their size. Shortest-witness details and witness-level AM statistics may differ depending on which edge is selected when both a dependency edge and an RT edge connect the same two transactions. The included outputs prefer the dependency edge, whereas the paper uses RT-edge priority. This causes slight numerical differences, but the overall trends remain unchanged.

License

This project is licensed under the MIT License; see LICENSE.

Some components retain separate third-party licenses. In particular, the YCSB-derived Zipf key selector contains Apache-2.0-licensed material. See NOTICE and LICENSES/Apache-2.0.txt. Git submodules retain their respective upstream licenses.