vindexes: expose unknown params

content/en/docs/18.0/reference/features/vindexes.md

@@ -149,7 +149,7 @@ Vindexes are defined in the [VSchema](../vschema/) inside the `Vindexes` section
 
 In the above case, the name of the vindex is `name_keyspace_idx`. It is of type `lookup`, and it is owned by the `user` table.
 
-Every Vindex has an optional `params` section that contains a map of string key-value pairs. The keys and values differ depending on the vindex type and are explained below. 
+Every Vindex has an optional `params` section that contains a map of string key-value pairs. The keys and values differ depending on the vindex type and are explained below.
 
 There is an optional fourth parameter: `batch_lookup`. To read more about how to use `batch_lookup` see our [Unique Lookup user guide](../../../user-guides/vschema-guide/unique-lookup/).
 
@@ -322,3 +322,27 @@ hex_keyspace_id: d9e62c0ad204fe91658ecc758049e515
 1 row in set (0.00 sec)
 
 ```
+
+### Unknown Vindex parameters
+
+Most Vindexes will accept unknown parameters without complaint. For example, the following `lookup` Vindex can be applied without error:
+
+```json
+    "name_keyspace_idx": {
+      "type": "lookup",
+      "params": {
+        "table": "name_keyspace_idx",
+        "from": "name",
+        "to": "keyspace_id",
+        "rear_lock": "none"
+      },
+      "owner": "user"
+    }
+```
+
+In this example, the user intended to use `read_lock` but typed `rear_lock` by mistake. They will be in for an unpleasant surprise during the traffic peak and `rear_lock` does nothing to mitigate lock contention.
+
+To help users avoid these kinds of unpleasant surprises, Vindexes may expose unknown parameters in the following ways:
+
+ * [As warnings](../../programs/vtctl/schema-version-permissions/#warnings) in the output of `ApplyVSchema`.
+ * As a [VTGate stat](../../../user-guides/configuration-basic/monitoring/#vindexunknownparameters) named `VindexUnknownParameters`.

content/en/docs/18.0/reference/programs/vtctl/schema-version-permissions.md

@@ -327,10 +327,14 @@ Applies the VTGate routing schema to the provided keyspace. Shows the result aft
 
 #### Errors
 
-* The <code>&lt;keyspace&gt;</code> argument is required for the <code>&lt;ApplyVSchema&gt;</code> command This error occurs if the command is not called with exactly one argument.
+* The <code>&lt;keyspace&gt;</code> argument is required for the <code>&lt;ApplyVSchema&gt;</code> command. This error occurs if the command is not called with exactly one argument.
 * Either the <code>&lt;vschema&gt;</code> or <code>&lt;vschema&gt;</code>File flag must be specified when calling the <code>&lt;ApplyVSchema&gt;</code> command.
 * If using a file you may need to pass the absolute path.
 
+#### Warnings
+
+* In some cases, unknown params passed to Vindexes may be accepted but reported as warnings in the command response.
+
 ### GetRoutingRules
 
 ```

content/en/docs/18.0/user-guides/configuration-basic/monitoring.md

@@ -370,10 +370,14 @@ This is the main histogram variable to track for vtgates. It gives you a break u
 
 It shows the number of tablet connections for query/healthcheck per keyspace, shard, and tablet type.
 
-### TopologyWatcherErrors and TopologyWatcherOperations
+#### TopologyWatcherErrors and TopologyWatcherOperations
 
 These two variables track events related to how vtgate watches the topology. It is particularly important to monitor the error count. This can act as an early warning sign if a vtgate is not able to refresh the list of tablets from the topo.
 
+#### VindexUnknownParameters
+
+Gauges the number of unknown Vindex params in the latest VSchema obtained from the topology.
+
 ### /debug/health
 
 This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy.