From 2ffbd21bf530e0dc5ed668c6dd85ad7086df8805 Mon Sep 17 00:00:00 2001 From: Max Englander Date: Sat, 22 Jun 2024 12:35:39 -0400 Subject: [PATCH] document mirror rules Signed-off-by: Max Englander --- .../reference/features/schema-mirror-rules.md | 75 +++++++++++++++++++ .../21.0/reference/vreplication/movetables.md | 10 +++ .../21.0/user-guides/migration/move-tables.md | 16 ++++ 3 files changed, 101 insertions(+) create mode 100644 content/en/docs/21.0/reference/features/schema-mirror-rules.md diff --git a/content/en/docs/21.0/reference/features/schema-mirror-rules.md b/content/en/docs/21.0/reference/features/schema-mirror-rules.md new file mode 100644 index 000000000..c8aacd36a --- /dev/null +++ b/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 `@`; `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. diff --git a/content/en/docs/21.0/reference/vreplication/movetables.md b/content/en/docs/21.0/reference/vreplication/movetables.md index 0ca61cb88..e34101d98 100644 --- a/content/en/docs/21.0/reference/vreplication/movetables.md +++ b/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 +#### MirrorTraffic +
+ +[`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`. + +
+ + #### SwitchTraffic
diff --git a/content/en/docs/21.0/user-guides/migration/move-tables.md b/content/en/docs/21.0/user-guides/migration/move-tables.md index 331646dfd..2f0279383 100644 --- a/content/en/docs/21.0/user-guides/migration/move-tables.md +++ b/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. {{}} +## 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