WIP

doc/humming-consensus-demo.md

@@ -72,6 +72,20 @@ Please run this script using this command:
 
     ./priv/humming-consensus-demo.setup.sh
 
+If the output looks like this (and exits with status zero), then the
+script was successful.
+
+    Step: Verify that the required entries in /etc/hosts are present
+    Step: add a verbose logging option to app.config
+    Step: start three three Machi application instances
+    pong
+    pong
+    pong
+    Step: configure one chain to start a Humming Consensus group with three members
+    Result: ok
+    Result: ok
+    Result: ok
+
 We have now created a single replica chain, called `c1`, that has
 three file servers participating in the chain.  Thanks to the
 hostnames that we added to `/etc/hosts`, all are using the localhost
@@ -88,6 +102,49 @@ The log files for each application instance can be found in the
 `./dev/devN/log/console.log` file, where the `N` is the instance
 number: 1, 2, or 3.
 
+## Understanding the chain manager's log file output
+
+After running the `./priv/humming-consensus-demo.setup.sh` script,
+let's look at the last few lines of the `./dev/dev1/log/console.log`
+log file for Erlang VM process #1.
+
+    2016-03-09 10:16:35.676 [info] <0.105.0>@machi_lifecycle_mgr:process_pending_flu:422 Started FLU f1 with supervisor pid <0.128.0>
+    2016-03-09 10:16:35.676 [info] <0.105.0>@machi_lifecycle_mgr:move_to_flu_config:540 Creating FLU config file f1
+    2016-03-09 10:16:35.790 [info] <0.105.0>@machi_lifecycle_mgr:bootstrap_chain2:312 Configured chain c1 via FLU f1 to mode=ap_mode all=[f1,f2,f3] witnesses=[]
+    2016-03-09 10:16:35.790 [info] <0.105.0>@machi_lifecycle_mgr:move_to_chain_config:546 Creating chain config file c1
+    2016-03-09 10:16:44.139 [info] <0.132.0> CONFIRM epoch 1141 <<155,42,7,221>> upi [] rep [] auth f1 by f1
+    2016-03-09 10:16:44.271 [info] <0.132.0> CONFIRM epoch 1148 <<57,213,154,16>> upi [f1] rep [] auth f1 by f1
+    2016-03-09 10:16:44.864 [info] <0.132.0> CONFIRM epoch 1151 <<239,29,39,70>> upi [f1] rep [f3] auth f1 by f1
+    2016-03-09 10:16:45.235 [info] <0.132.0> CONFIRM epoch 1152 <<173,17,66,225>> upi [f2] rep [f1,f3] auth f2 by f1
+    2016-03-09 10:16:47.343 [info] <0.132.0> CONFIRM epoch 1154 <<154,231,224,149>> upi [f2,f1,f3] rep [] auth f2 by f1
+
+Let's pick apart some of these lines.
+
+* `Started FLU f1 with supervisor pid <0.128.0>` ; This VM, #1,
+  started a FLU (Machi data server) with the name `f1`.  In the Erlang
+  process supervisor hierarchy, the process ID of the top supervisor
+  is `<0.128.0>`.
+* `Configured chain c1 via FLU f1 to mode=ap_mode all=[f1,f2,f3] witnesses=[]`
+  A bootstrap configuration for a chain named `c1` has been created.
+  * The FLUs/data servers that are eligible for participation in the
+    chain have names `f1`, `f2`, and `f3`.
+  * The chain will operate in eventual consistency mode (`ap_mode`)
+  * The witness server list is empty.  Witness servers are never used
+    in eventual consistency mode.
+* `CONFIRM epoch 1141 <<155,42,7,221>> upi [] rep [] auth f1 by f1`
+  * All participants in epoch 1141 are unanimous in adopting epoch
+    1141's projection.  All active membership lists are empty, so
+    there is no functional chain replication yet, at least as far as
+    server `f1` knows
+  * The epoch's abbreviated checksum is `<<155,42,7,221>>`.
+  * The UPI list, i.e. the replicas whose data is 100% in sync is
+    `[]`, the empty list.  (UPI = Update Propagation Invariant)
+  * The list of servers that are under data repair (`rep`) is also
+    empty, `[]`.
+  * This projection was authored by server `f1`.
+  * The log message was generated by server `f1`.
+
+
 <a name="partition-simulator">
 # Using the network partition simulator and convergence demo test code