Skip to content
This repository was archived by the owner on Sep 25, 2020. It is now read-only.

Improve running_ringpop.md #82

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Improve running_ringpop.md #82

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2c317c6
Add note about broken table in RST
motiejus Jun 27, 2016
794386f
ring.change is a counter
motiejus Jun 27, 2016
962ae42
Document location of tick-cluster
motiejus Jun 27, 2016
412aeaa
Add {membership,ring}.checksum-periodic
motiejus Jun 27, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions docs/running_ringpop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]:uber/ringpop.git
$ git clone [email protected]: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] <ringpop-program>
$ ./tick-cluster.js [-n size-of-cluster] [-i interpreter-that-runs-program] <ringpop-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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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