begin documentation on sub-second replication lag throttling

doc/cheatsheet.md

@@ -104,7 +104,7 @@ gh-ost \
   --initially-drop-old-table \
   --max-load=Threads_running=30 \
   --switch-to-rbr \
-  --chunk-size=2500 \
+  --chunk-size=500 \
   --cut-over=default \
   --exact-rowcount \
   --concurrent-rowcount \

doc/command-line-flags.md

@@ -68,6 +68,19 @@ We think `gh-ost` should not take chances or make assumptions about the user's t
 
 See #initially-drop-ghost-table
 
+### max-lag-millis
+
+On a replication topology, this is perhaps the most important migration throttling factor: the maximum lag allowed for migration to work. If lag exceeds this value, migration throttles.
+
+When using [Connect to replica, migrate on master](cheatsheet.md), this lag is primarily tested on the very replica `gh-ost` operates on. Lag is measured by checking the heartbeat events injected by `gh-ost` itself on the utility changelog table. That is, to measure this replica's lag, `gh-ost` doesn't need to issue `show slave status` nor have any external heartbeat mechanism.
+
+When `--throttle-control-replicas` is provided, throttling also considers lag on specified hosts. Measuring lag on these hosts works as follows:
+
+- If `--replication-lag-query` is provided, use the query, trust its result to indicate lag seconds (fraction, i.e. float, allowed)
+- Otherwise, issue `show slave status` and read `Seconds_behind_master` (`1sec` granularity)
+
+See also: [Sub-second replication lag throttling](subsecond-lag.md)
+
 ### migrate-on-replica
 
 Typically `gh-ost` is used to migrate tables on a master. If you wish to only perform the migration in full on a replica, connect `gh-ost` to said replica and pass `--migrate-on-replica`. `gh-ost` will briefly connect to the master but other issue no changes on the master. Migration will be fully executed on the replica, while making sure to maintain a small replication lag.

doc/perks.md

@@ -58,3 +58,7 @@ You begin a migration, and the ETA is for it to complete at 04:00am. Not a good
 Today, DBAs are coordinating the migration start time such that it completes in a convenient hour. `gh-ost` offers an alternative: postpone the final cut-over phase till you're ready.
 
 Execute `gh-ost` with `--postpone-cut-over-flag-file=/path/to/flag.file`. As long as this file exists, `gh-ost` will not take the final cut-over step. It will complete the row copy, and continue to synchronize the tables by continuously applying changes made on the original table onto the ghost table. It can do so on and on and on. When you're finally ready, remove the file and cut-over will take place.
+
+### Sub-second lag throttling
+
+With sub-second replication lag measurements, `gh-ost` is able to keep a fleet of replicas well below `1sec` lag throughout the migration. We encourage you to issue sub-second heartbeats. Read more on [sub-second replication lag throttling](subsecond-lag.md)

doc/subsecond-lag.md

@@ -0,0 +1,3 @@
+# Sub-second replication lag throttling
+
+`gh-ost` is able to utilize sub-second replication lag measurements. We strongly suggest