document mirror rules

content/en/docs/21.0/reference/features/schema-mirror-rules.md

@@ -0,0 +1,75 @@
+---
+title: Schema Mirror Rules
+weight: 15
+---
+
+Mirror rules are a feature for testing how queries will perform when executed against a different keyspace. It is intended to reduce the uncertainty involved when migrating application queries from one keyspace to another via `MoveTables`.
+
+## Viewing Mirror Rules
+
+The mirror rules are global and can be viewed using the [`GetMirrorRules` client command](../../programs/vtctldclient/vtctldclient_getmirrorrules/).
+
+## Updating Mirror Rules
+
+Mirror rules are managed by the [`MoveTables MirrorTraffic` client command](../../programs/vtctldclient/vtctldclient_getmirrorrules/). For advanced use cases, you can manage mirror rules using the [`ApplyMirrorRules` client command](../../programs/vtctldclient/vtctldclient_applymirrorrules/).
+
+## Syntax
+
+Mirror rules are managed using the JSON format. Here's an example, showing the mirror rules that would be produced using `MoveTables MirrorTraffic` against the [local examples](../../../get-started/local/), where the queries to `customer` and `corder` tables are mirrored from the the `commerce` keyspace to the `customer` keyspace:
+
+```bash
+$ vtctldclient --server=localhost:15999 GetMirrorRules
+{
+  "rules": [
+    {
+      "from_table": "commerce.corder",
+      "to_table": "customer.corder",
+      "percent": 1.0
+    },
+    {
+      "from_table": "commerce.corder@replica",
+      "to_table": "customer.corder",
+      "percent": 1.0
+    },
+    {
+      "from_table": "commerce.corder@rdonly",
+      "to_table": "customer.corder",
+      "percent": 1.0
+    },
+    {
+      "from_table": "commerce.customer",
+      "to_table": "customer.customer",
+      "percent": 1.0
+    },
+    {
+      "from_table": "commerce.customer@replica",
+      "to_table": "customer.customer",
+      "percent": 1.0
+    },
+    {
+      "from_table": "commerce.customer@rdonly",
+      "to_table": "customer.customer",
+      "percent": 1.0
+    }
+  ]
+}
+```
+
+## When Mirror Rules Are Applied
+
+Mirror rules are evaluated after routing rules. So, if there are routing rules in place redirecting traffic from `commerce` tables to `customer` tables, then the mirror rules in the example above would not be applied.
+
+## Evaluating the Impact of Mirror Rules
+
+At the moment, there are no VTGate-level metrics reporting the performance of mirrored queries. Check [VTTablet-level metrics](../../configuration-basic/monitoring/) to observe the performance of mirrored queries.
+
+## Additional Details
+
+For most cases, you should use `MoveTables MirrorTraffic` to manage mirror rules. Here are some details to keep in mind if you will be creating and managing your own custom mirror rules:
+
+- `from_table` may optionally specify a `@<tablet-type>`; `to_table` may not.
+- `from_table` and `to_table` must both be fully qualified.
+- For a given `from_table` value, there can be at most one mirror rule.
+- A keyspace that is named in the `from_table` of one rule may not be named in the `to_table` of that rule or any other rule.
+- `percent` may be a value between `0` and `100`, inclusive.
+- Setting `percent` to `0` removes that mirror rule.

content/en/docs/21.0/reference/vreplication/movetables.md

@@ -75,6 +75,16 @@ It is too expensive to get real-time row counts of tables, using _count(*)_, say
 
 </div>
 
+#### MirrorTraffic
+<div class="cmd">
+
+[`mirrortraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_mirrortraffic/) mirrors a percentage of traffic forward for the `tablet-types` specified.
+
+`mirrortraffic` must be run before `switchtraffic`. `switchtraffic` will automatically remove any mirror rules that were created by `mirrortraffic`.
+
+</div>
+
+
 #### SwitchTraffic
 <div class="cmd">
 

content/en/docs/21.0/user-guides/migration/move-tables.md

@@ -486,6 +486,22 @@ $ vtctldclient VDiff --format=json --target-keyspace customer --workflow commerc
 This can take a long time to complete on very large tables.
 {{</ info >}}
 
+## Mirroring Traffic
+
+Optionally, you can test how queries will perform once traffic is switched by mirroring traffic from the source keyspace to the target keyspace. A mirrored query will be routed to the source keyspace (`commerce`), and a copy of that query will be sent to the target keyspace (`customer`). Results and errors from the source keyspace will be returned to the client, while results and errors from the target keyspace wil be ignored.
+
+```bash
+$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer MirrorTraffic --percent 1.0
+SwitchTraffic was successful for workflow customer.commerce2customer
+
+Start State: Reads Not Switched. Writes Not Switched
+Current State: All Reads Switched. Writes Switched
+```
+
+`MirrorTraffic` increases VTGate CPU usage and memory allocations, while decreasing performance. It is recommended to start with small values of `--percent` (between `0` and `1`), and increase in small increments. If you observe decreases in performance or increases in VTGate memory usage, either revert to smaller values of `--percent` or increase the amount of resources allocated to VTGate.
+
+Check [VTTablet-level metrics](../configuration-basic/monitoring/) in the target keyspace to see how queries are performing there.
+
 ## Switching Traffic
 
 Once the `MoveTables` operation is complete ([in the "running" or replicating phase](../../../../design-docs/vreplication/life-of-a-stream/)), the first step in making the changes live is to _switch_ all query serving