test/tools/clustering/cluster-monitor/README.markdown

   1 # Cluster Monitor Tool
   2
   3 This tool provides real-time visualization of the cluster member roles for all
   4 shards in the config datastore. It is useful for understanding cluster behavior
   5 in when controllers are isolated, downed, or rebooted.
   6
   7 A file named `cluster.json` containing a list of the IP addresses of the
   8 controllers is required. This resides in the same directory as `monitor.py`.
   9 "user" and "pass" are not required for `monitor.py`, but they may be
  10 needed for other apps in this folder. Because this configuration
  11 information unique to your environment, it may be more convenient to
  12 copy the contents of this folder out of git to prevent these settings
  13 from being overwritten by updates.
  14
  15
  16 The file should look like this:
  17
  18 ```
  19     {
  20         "cluster": {
  21             "controllers": [
  22                 "172.17.10.93",
  23                 "172.17.10.94",
  24                 "172.17.10.95"
  25             ],
  26             "user": "username",
  27             "pass": "password"
  28         }
  29     }
  30 ```
  31
  32 ## Usage: `monitor.py`
  33
  34 ### Starting `monitor.py`
  35
  36 Before using, start and configure all controllers in the cluster. Use of the
  37 cluster deployment script is recommended. All controllers must initially be
  38 running so the tool can retrieve the controller and shard names. Once
  39 the tool is started and the controller and cluster shard names are retrieved,
  40 controllers can be isolated, downed, rebooted, etc.
  41
  42 ### The `monitor.py` UI
  43
  44 Controller member names (not host names) are displayed across the top. Shard
  45 names are displayed to the left.
  46
  47 In the upper left is a heart emoticon "<3" which toggles between yellow and
  48 black backgrounds with each update. If a controller is down, the HTTP timeout
  49 comes in to play and updating becomes much slower.
  50
  51 The central matrix displays controller roles. When REST queries fail, the
  52 error type is displayed. Leader, Follower, and Candidate roles are color-
  53 coded.
  54
  55 ## Other Scripts
  56
  57 ### `isolate.py`
  58
  59 Isolates an indicated controller from the cluster.
  60
  61 ### `rejoin.py`
  62
  63 Rejoins any isolated controllers to the cluster.
  64
  65 ### `timed_isolation.py`
  66
  67 Isolates an indicated controller for a specified duration
  68
  69 ## Future Enhancements
  70
  71 Add operational shards.