{"id":13670953,"url":"https://github.com/tikv/jepsen-test","last_synced_at":"2025-07-02T23:35:17.247Z","repository":{"id":66192343,"uuid":"387439851","full_name":"tikv/jepsen-test","owner":"tikv","description":null,"archived":false,"fork":false,"pushed_at":"2021-08-05T05:44:08.000Z","size":87,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-22T23:39:07.703Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tikv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-07-19T11:25:53.000Z","updated_at":"2024-08-10T16:32:11.000Z","dependencies_parsed_at":"2023-02-25T07:00:14.208Z","dependency_job_id":null,"html_url":"https://github.com/tikv/jepsen-test","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tikv/jepsen-test","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Fjepsen-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Fjepsen-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Fjepsen-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Fjepsen-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tikv","download_url":"https://codeload.github.com/tikv/jepsen-test/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tikv%2Fjepsen-test/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263233955,"owners_count":23434890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T09:00:54.191Z","updated_at":"2025-07-02T23:35:16.121Z","avatar_url":"https://github.com/tikv.png","language":"Clojure","funding_links":[],"categories":["Clojure"],"sub_categories":[],"readme":"# jepsen.tikv\n\nJepsen test for TiKV.\n\n## Build\n\n```bash\n# generate clojure client from protobuf\nmake gen-proto-clojure-client\n# build rust-client-server which will be referenced by `./rpc-server`\nmake build-rust-client-server\n```\n\n## Usage\n\n1. Install LXC using `scripts/install-lxc.h`.\n\n2. Set up tester using `scripts/setup-tester.sh`.\n\n3. Set up virtual network using `scripts/setup-network.sh`.\n\n4. Generate RSA key pair.\n```bash\nssh-keygen -t rsa\n```\n\n5. Set up nodes via LXC using `scripts/setup-nodes.sh`, `scripts/prepare-nodes.sh`.\n\n6. Build rust-client-server\n```bash\nmake build-rust-client-server\n```\n\n7. Run the test on nodes:\n```bash\nxvfb-run lein run test --ssh-private-key ~/.ssh/id_rsa --version v4.0.0 --workload register --concurrency 10 --leave-db-running --time-limit 30\n```\n\n## Architecture\n\nWhen we run a Jepsen test, we need several test nodes to deploy our databases, and a control node which runs the tests written in Clojure. Under our circustance, we setup 5 CentOS 7 nodes via LXC and make sure it can be logged in via ssh from control node, which is the host.\n\nThe whole process of running a Jepsen test consist of four phases. First, we try to tear down the database if it's already running, and setup a brand-new database on test nodes. And then, we run specific workloads on it and record everything we observe from the client-side as a history. Third, we analyze the history with a specific model and a checker to see whether it shows any anomolies. Finally, we tear down the databases (This pharse will be skipped if `--leave-db-running` option is present).\n\nEach workload usually has more than one concurrent unit. In Jepsen, it is called a process. Each process executes operations in a blocking way. Each process create a client connected to a specific node for operations.\n\nNormally, the client is implemented natively in Clojure. But in our case, we implement it in a \"client server\" way.\nWhile setting up each test node, we also start a \"client server\" connected to the node. The \"client server\" exposes a RPC service for the TiKV client implemented in Clojure.\n\n```\n┌───────────────────────────────────────────┐   ┌─────────────┐\n│                                           │   │             │\n│                               ┌────────┐  │   │   ┌──────┐  │\n│    ┌─────────────────┐   ┌───►│ client ├──┼───┼──►│ node │  │\n│    │     Jepsen      │   │    │ server │  │   │   └──────┘  │\n│    │                 │   │    └────────┘  │   │             │\n│    │   ┌─────────┐   │   │                │   │             │\n│    │   │ Process ├───┼───┘    ┌────────┐  │   │   ┌──────┐  │\n│    │   └─────────┘   │        │ client ├──┼───┼──►│ node │  │\n│    │                 │        │ server │  │   │   └──────┘  │\n│    │   ┌─────────┐   │        └────────┘  │   │             │\n│    │   │ Process ├───┼───┐                │   │             │\n│    │   └─────────┘   │   │    ┌────────┐  │   │   ┌──────┐  │\n│    │       .         │   └───►│ client ├──┼───┼──►│ node │  │\n│    │       .         │        │ server │  │   │   └──────┘  │\n│    │       .         │        └────────┘  │   │             │\n│    │       .         │                    │   │             │\n│    │       .         │        ┌────────┐  │   │   ┌──────┐  │\n│    │       .         │        │ client ├──┼───┼──►│ node │  │\n│    │   ┌─────────┐   │        │ server │  │   │   └──────┘  │\n│    │   │ Process ├───┼───┐    └────────┘  │   │             │\n│    │   └─────────┘   │   │                │   │             │\n│    │                 │   │    ┌────────┐  │   │   ┌──────┐  │\n│    │                 │   └───►│ client ├──┼───┼──►│ node │  │\n│    └─────────────────┘        │ server │  │   │   └──────┘  │\n│                               └────────┘  │   │             │\n│                                           │   │             │\n│                    Host                   │   │     LXC     │\n└───────────────────────────────────────────┘   └─────────────┘\n```\n\n## Workload\n\n- **register** concurrent atomic updates to multiple shared registers\n- **set** concurrent unique appends to a single key\n- **list-append** Checks for dependency cycles in append/read transactions\n\n## License\n\nTiKV is under the Apache 2.0 license. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftikv%2Fjepsen-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftikv%2Fjepsen-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftikv%2Fjepsen-test/lists"}