Document latest functionalities

global-refdb update-ref and localrefdb had not been documented.

Change-Id: I6c0cf34f921a0956518c2666ec43dd61644c4cd9

multi-primary/README.md

diff --git a/multi-primary/README.md b/multi-primary/README.md
index cb7d092..a3a9cd8 100644
--- a/multi-primary/README.md
+++ b/multi-primary/README.md
@@ -8,4 +8,10 @@
 
 Index
 -----
-* [globalrefdb](globalrefdb.md) - Checks the repository local-refdb vs. global-refdb
+* [globalrefdb](globalrefdb.md) - Provides utility to check and update local
+refs against the globalrefdb:
+ - Checks the repository local-refdb vs. global-refdb
+ - Allows updating globalrefdb to a specific sha1 value
+* [localalrefdb](localrefdb.md) - Provides ssh commands that create metrics for:
+ - Number of refs in project
+ - Combined SHA1 of all refs in project

multi-primary/globalrefdb.md

diff --git a/multi-primary/globalrefdb.md b/multi-primary/globalrefdb.md
index 17f74f6..45a5d0f 100644
--- a/multi-primary/globalrefdb.md
+++ b/multi-primary/globalrefdb.md
@@ -1,20 +1,32 @@
-Global-refdb Check utility
+Global-refdb utility
 ==============================
 
-NAME
+COMMANDS
 ----
-`globalrefdb check` utility compare the repository refs status against the global-refdb.
+`globalrefdb check` utility compare the repository refs status against
+the global-refdb.
+`globalrefdb update-ref` utility to manually update global-refdb entry
+in the eventuality that global-refdb is out of sync with all other nodes.
+
 
 SYNOPSIS
 --------
 >     ssh -p <port> <host> globalrefdb check PROJECT [--ref <ref name>] [--verbose]
+>     ssh -p <port> <host> globalrefdb update-ref PROJECT REF-NAME NEW-VALUE
 
 DESCRIPTION
 -----------
+
+## Check
 Verify if the local with the global refs for a project, reporting all differences
 between the two SHA1s. The operation can operate on the individual ref passed as
 a parameter.
 
+## Update-ref
+Update global-refdb in case we cannot automatically deduce which ref is
+the latest.
+This can happen if the global-refdb finds itself behind other nodes.
+
 ACCESS
 ------
 Any user who has been granted the 'Administrate Server' capability.
@@ -28,3 +40,7 @@
 Check if all refs of the All-Users project are up-to-date with the global-refdb:
 
 >     $ ssh -p 29418 review.example.com globalrefdb check All-Users
+
+Update global-refdb's sha1
+
+>     $ ssh -p 29418 review.example.com globalrefdb update-ref All-Users refs/draft-comments/nn/nnnn/nn <sha1>

multi-primary/localrefdb.md

diff --git a/multi-primary/localrefdb.md b/multi-primary/localrefdb.md
new file mode 100644
index 0000000..8973694
--- /dev/null
+++ b/multi-primary/localrefdb.md
@@ -0,0 +1,56 @@
+Local-refdb utility
+==============================
+
+COMMANDS
+----
+`localrefdb count-refs` utility to count the number of refs per project and
+register a metric called `num_ref_per_project_<project name>`
+`localrefdb sha1-all-refs` utility to combine the SHA1s of all refs into a
+new SHA1 and produce a numeric representation of it.
+This will also register a metric called:
+`sha1_all_refs_per_project_<project name>`
+
+
+SYNOPSIS
+--------
+>     ssh -p <port> <host> localrefdb count-refs PROJECT [--verbose]
+>     ssh -p <port> <host> localrefdb sha1-all-refs PROJECT [--verbose]
+
+DESCRIPTION
+-----------
+
+## Count-refs
+A metric generated by a count of all refs in a project except for the
+user-edit refs, as these are not usually replicated.
+
+## Sha1-all-refs
+A metric generated by combining all SHA1s in a project except for the
+user-edit refs, as these are not usually replicated.
+The SHA1 is then converted into a numerical value so that a metric can
+be registered.
+
+This can be useful to avoid scenarios where refs are different but their
+counts match.
+In this case, the numerical value provided by this metric will be different
+for each node hence highlighting a discrepancy.
+
+This command should be ideally executed during a readonly window,
+to avoid ongoing replication tasks affecting the result.
+
+ACCESS
+------
+Any user who has been granted the 'Administrate Server' capability.
+
+SCRIPTING
+---------
+This command is intended to be used in scripts.
+
+EXAMPLES
+--------
+Count refs in project
+
+>     $ ssh -p 29418 review.example.com localrefdb count-refs All-Users
+
+Update global-refdb's sha1
+
+>     $ ssh -p 29418 review.example.com localrefdb sha1-all-refs All-Users