diff --git a/docs/running_ringpop.md b/docs/running_ringpop.md index 6d930e5..a1521ff 100644 --- a/docs/running_ringpop.md +++ b/docs/running_ringpop.md @@ -2,19 +2,20 @@ Before we get to programming against Ringpop, let's just run it by itself and see what happens. There are several ways to accomplish this and they are documented below. There's nothing too fancy going on when Ringpop runs by itself. To reap the full potential of it, you'll need to embed it into your application and start divvying incoming requests based on the sharding key of your choice. No matter, we're here, in this section, to get a look at what happens in Ringpop at steady-state, how its membership protocol behaves and how to launch a standalone version of it from the command-line. Let's get to it! ## Running with tick-cluster -`tick-cluster` is a utility located in the `scripts/` directory of the Ringpop repo that allows you to quickly spin up a Ringpop cluster of arbitrary size and test basic failure modes: suspending, killing and respawning nodes. +`tick-cluster` is a utility located in the `tools/` directory of this repo that allows you to quickly spin up a Ringpop cluster of arbitrary size and test basic failure modes: suspending, killing and respawning nodes. To use `tick-cluster`, first clone the repo and install Ringpop's dependencies: ``` -$ git clone git@github.com:uber/ringpop.git +$ git clone git@github.com:uber/ringpop-common.git +$ cd tools $ npm install ``` Then run `tick-cluster`: ``` -$ ./scripts/tick-cluster.js [-n size-of-cluster] [-i interpreter-that-runs-program] +$ ./tick-cluster.js [-n size-of-cluster] [-i interpreter-that-runs-program] ``` `tick-cluster` will spawn a child process for each node in the cluster. They will bootstrap themselves using an auto-generated `hosts.json` bootstrap file and converge on a single membership list within seconds. Commands can be issued against the cluster while `tick-cluster` runs. Press `h` or `?` to see which commands are available. @@ -24,7 +25,7 @@ Whenever it is specified, the program is run by an interpreter, otherwise the pr Here's a sample of the output you may see after launching a 7-node cluster with `tick-cluster`: ``` -$ ./scripts/tick-cluster.js -n 7 -i node ./main.js +$ ./tick-cluster.js -n 7 -i node ./main.js [init] 11:11:52.805 tick-cluster started d: debug flags, g: gossip, j: join, k: kill, K: revive all, l: sleep, p: protocol stats, q: quit, s: cluster stats, t: tick [cluster] 11:11:52.807 using 10.80.135.224 to listen [init] 11:11:52.818 started 7 procs: 76365, 76366, 76367, 76368, 76369, 76370, 76371 @@ -49,6 +50,10 @@ identity in the stat path, e.g. `ringpop.10_30_8_26_20600.*`; the dots and colon are replaced by underscores. The table below lists all stats that Ringpop emits: +*Note: if you are reading this page from ringpop.readthedocs.org, the table +below is probably broken, and we [can't do anything about it yet][1]. For a +properly-formatted table, please see [this page on github][2].* + |Node.js Path|Description|Type |----|----|---- |changes.apply|Number of changes applied per membership update|gauge @@ -92,6 +97,7 @@ that Ringpop emits: |membership-update.leave|A member was updated in the leave state|count |membership-update.suspect|A member was updated to be suspect|count |membership-update.unknown|A member was updated in the unknown state|count +|membership.checksum-periodic|Current membership checksum|gauge |membership.checksum-computed|Membership checksum was computed|count |not-ready.ping|Ping received before Ringpop was ready|count |not-ready.ping-req|Ping-req received before Ringpop was ready|count @@ -124,8 +130,9 @@ that Ringpop emits: |requestProxy.retry.succeeded|Forwarded request succeeded after retries|count |requestProxy.send.error|Forwarded request failed|count |requestProxy.send.success|Forwarded request was successful|count -|ring.change|Hash ring keyspace changed|gauge +|ring.change|Hash ring keyspace changed|counter |ring.checksum-computed|Hash ring checksum was computed|count +|ring.checksum-periodic|Current ring checksum|gauge |ring.server-added|Node (and its points) added to hash ring|count |ring.server-removed|Node (and its points) removed from hash ring|count |updates|Number of membership updates applied|timer @@ -135,3 +142,6 @@ Content coming soon... ## Troubleshooting Content coming soon... + +[1]: https://github.com/rtfd/recommonmark/issues/3 +[2]: https://github.com/uber/ringpop-common/blob/master/docs/running_ringpop.md#monitoring