From be5f929530c3f221ca732044fbbc16998cf114e4 Mon Sep 17 00:00:00 2001 From: Matt Lord Date: Tue, 27 Dec 2022 19:59:06 -0500 Subject: [PATCH] Document all RPC parameters and flags Signed-off-by: Matt Lord --- .../16.0/reference/vreplication/vstream.md | 69 ++++++++++++++++--- 1 file changed, 58 insertions(+), 11 deletions(-) diff --git a/content/en/docs/16.0/reference/vreplication/vstream.md b/content/en/docs/16.0/reference/vreplication/vstream.md index 8901ffc84e..58c8c90267 100644 --- a/content/en/docs/16.0/reference/vreplication/vstream.md +++ b/content/en/docs/16.0/reference/vreplication/vstream.md @@ -37,24 +37,68 @@ environments by many Vitess users. [VStreamRequest](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamRequest) to a `vtgate` process's `--grpc_port` and receive a [VStreamResponse](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamResponse). -As part of the gRPC request, you can specify the following -[flags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags): +As part of the gRPC request, you can specify optional +[flags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags). -#### MinimizeSkew +### RPC Parameters + +#### Context + +**Type** [Context](https://pkg.go.dev/context#Context)\ +**Required**\ +**Default** none + +In addition to the typical Context fields, it can contain CallerID keys — the immedate caller ID being key `0` +and the effective caller ID being key `1` — and those values are passed along to identify the originating client +for a request. It is not meant to be secure, but only informational. The client can put whatever info they want +in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and +to easily find a client. The `vtgate` propagates it to the source `vttablet` processes and the tablets may use +this information for monitoring purposes, to display on dashboards, or for denying access to tables during a +migration. + +#### TabletType + +**Type** [TabletType](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/topodata#TabletType)\ +**Required**\ +**Default** UNKNOWN (you must specify a valid type) + +The tablet type to use [when selecting stream source tablets](../tablet_selection/). + +#### VGtid + +**Type** [VGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid)\ +**Required** + +The keyspace, shard, and GTID position list to start streaming from. If no `ShardGtids.Gtid` value is provided +then a [table copy phase](https://vitess.io/docs/design-docs/vreplication/vstream/vscopy/) will be initiated +for the tables matched by the provided [filter](#filter). + +#### Filter + +**Type** [Filter](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#Filter)\ +**Required** + +The tables which you want to subscribe to change events from — in the given keyspace(s) and shard(s) contained +in the provided [VGtid](#vgtid) — and any query predicates to use when filtering the rows for which change +events will be generated. + +#### VStreamFlags + +##### MinimizeSkew **Type** bool\ **Default** false When enabled the `vtgate` will keep the events in the stream roughly time aligned — it is aggregating streams coming -from each of the shards involved — using the event timestamps to ensure the maximum time skew between the streams is -under 10 minutes. When it detects skew between the base shard streams it will pause sending the client more events and allow the lagging shard(s) -to catch up. +from each of the shards involved — using the event timestamps to ensure the maximum time skew between the source +tablet shard streams is kept under 10 minutes. When it detects skew between the source streams it will pause sending +the client more events and allow the lagging shard(s) to catch up. {{< info >}} -Note that the order is not guaranteed across shards and the client will need to examine the event timestamps. +There is no strict ordering of events across shards and the client will need to examine the event timestamps. {{}} -#### HeartbeatInterval +##### HeartbeatInterval **Type** unsigned integer\ **Default** 0 (none) @@ -62,7 +106,7 @@ Note that the order is not guaranteed across shards and the client will need to How frequently, in seconds, to send heartbeat events to the client when there are no other events in the stream to send. -#### StopOnReshard +##### StopOnReshard **Type** bool\ **Default** false @@ -70,7 +114,7 @@ send. When enabled the `vtgate` will send reshard events to the client and stop sending any further events for the current [VStreamRequest](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamRequest). -#### Cells +##### Cells **Type** string\ **Default** "" @@ -79,7 +123,7 @@ If specified, these cells (comma-separated list) are used [when selecting stream source tablets](../tablet_selection/). When no value is specified the `vtgate` will default to looking for source tablets within its own local cell. -### Types +### Service Types * [VStreamRequest](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamRequest) * [VStreamResponse](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamResponse) * [VStreamFlags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) @@ -87,6 +131,9 @@ default to looking for source tablets within its own local cell. * [VGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid) * [LastPKEvent](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#LastPKEvent) * [TableLastPK](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#TableLastPK) + * [ShardGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#ShardGtid) + * [Filter.Rule](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#Rule) + * [TabletType](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/topodata#TabletType) ### Example Usage ```