package protocol.run

Get desktop application:
View/edit binary Protocol Buffers messages

For optimal streaming performance, batches of results can be returned.

Used in: Result

• repeated Result result = 1

Used in: Request

• optional ConfigStreaming streaming_config = 1

See CBD-4975 for discussion of streaming. The two main points are: 1. Naively sending back results one at a time did not scale. 2. Batching results in BatchedResults increased flow-rate by nearly 2 orders of magnitude.

The next two parameters are only mandatory on grpc.Workloads, which are explicitly testing various streaming approaches. Otherwise they should be regarded as optional hints. If the performer follows them then it will automatically get what has been tested to most reliably return results. But it can override them if it has done its own testing and found its own best path for that language.

Used in: Config

• optional int32 batch_size = 1

  If present, the performer should stream back BatchedResults, aiming to contain this number of results. The performer can return less elements than this in a batch (so it does not have to wait for a write queue to fill first).

• bool flow_control = 2

  Whether the performer should enable flow control. This will mean different things to different GRPC implementations, but the concept is to only send responses when the GRPC response stream reports itself ready. If the performer is unable to keep up with the flow rate then this effectively just moves the filling queue from GRPC's to one owned by the performer, but this can still be beneficial as the performer can keep better metrics on its own queue.

• bool enable_metrics = 3

  Whether the performer should stream back metrics.

"HorizontalScaling" is an abstraction over there being many forms of concurrency. The core idea is that the driver is trying to increase the parallelism, and it's up to the performer to choose a suitable platform-dependent way to do this. For some languages that will be threads. For some, a larger pool of concurrent Future/Promises. For some, forking a new process. Whatever is produced (thread, new process), it should run the provided workload(s) in a tight loop. So essentially HorizontalScaling is the number of concurrent operations taking place.

Used in: Workloads

• repeated Workload workloads = 1

  Performer will run these workloads in this 'thread-like', in the specified order.

Used as request type in: PerformerService.run

• optional Config config = 1

  Configures how the performer executes this run.

• oneof request

  What the performer should do in this run. A `oneof` for future extension.

  • Workloads workloads = 2

• map<string, string> tunables = 3

  Can apply SDK tunables that can't be represented generically in GRPC. One example is for performance testing, where we may want to experiment with various approaches in say the Java SDK. So one run may send "com.couchbase.executorMaxThreadCount"="10", and the next set it to "20". Interpretation of the tunables, and how to apply them inside the SDK, is completely SDK-dependent. Generally the performer should unset all tunables at the end of the run RPC. Generally performers can ignore this field unless they are explicitly planning on using it.

The performer returns a stream of run.Result to the driver. When and what results it should return, are detailed elsewhere in the GRPC.

Used as response type in: PerformerService.run

Used as field type in: BatchedResult

• oneof result

  • sdk.Result sdk = 3

    Each sdk.Command should return back one of these results.

  • meta.Result grpc = 4

    Each meta.Command should return back one of these results.

  • metrics.Result metrics = 5

    The performer can send back metrics whenever it wishes. However, due to the way database results are currently joined with the bucket results (which are in one second buckets), it's only useful to send back a maximum of one per second.

  • BatchedResult batched = 6

    For optimal streaming performance, batches of results can be returned.

  • streams.Signal stream = 7

    Something significant has happened on a stream (such as creation or completion). The actual streamed results will be returned elsewhere (usually as Results).

  • transactions.TransactionResult transaction = 8

    Result of a single transaction.

• int64 elapsedNanos = 1

  Performance times are always returned so it's easier for the performers to code-share between performance and integration testing. Clocks are hard. Many OS/platform combinations cannot guarantee nanosecond level precision of a wallclock time, but can provide such precision for elapsed time. So: `elapsedNanos` is intended to be, as precisely as the platform can measure it, the exact time taken by the operation in nanoseconds. Measured from just before sending the operation into the SDK (e.g. after handling any GRPC work and JSON conversion), and just after the SDK returns. To stress, this should not include any JSON or GRPC processing. `initiated` is a wallclock time, used to place this operation into a one second bucket. This should be as accurate as the platform can provide (often realistically this is only accurate to 10 millis or so). Hopefully a few operations ending up in the wrong bucket each second will not dramatically impact the results. It is ok to set `initiated` before the GRPC work, due to the reduced precision. For failed operations: `initiated` needs to be the wallclock time the operation was initiated, not when it failed which can be potentially X seconds later. `elapsedNanos` historically was not required by the performer, but some tests do now use it. The SDK can opt into these tests by always returning this field and declaring support for performer cap TIMING_ON_FAILED_OPS.

• optional google.protobuf.Timestamp initiated = 2

A workload is generally a bunch of commands to run.

Used in: HorizontalScaling

• oneof workload

  • sdk.Workload sdk = 1

  • meta.Workload grpc = 2

  • transactions.Workload transaction = 3

Allows running multiple Workloads concurrently.

Used in: Request

• string cluster_connection_id = 1

  The previously established cluster connection to use, for all operations instigated under this task. Operations below this that have their own clusterConnectionId (like TransactionCreateRequest) do _not_ override this value - any future exceptions to that rule will be explicitly documented here.

• repeated HorizontalScaling horizontal_scaling = 2

  See HorizontalScaling for a discussion of this. Broadly, it's the number of concurrent operations required.