package grpc.testing

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc UnaryCall (SimpleRequest, SimpleResponse)

  services.proto:28

  One request followed by one response. The server returns the client payload as-is.

• rpc StreamingCall (stream SimpleRequest, stream SimpleResponse)

  services.proto:33

  Repeated sequence of one request followed by one response. Should be called streaming ping-pong The server returns the client payload as-is on each response

• rpc StreamingFromClient (stream SimpleRequest, SimpleResponse)

  services.proto:37

  Single-sided unbounded streaming from client to server The server returns the client payload as-is once the client does WritesDone

• rpc StreamingFromServer (SimpleRequest, stream SimpleResponse)

  services.proto:41

  Single-sided unbounded streaming from server to client The server repeatedly returns the client payload as-is

• rpc StreamingBothWays (stream SimpleRequest, stream SimpleResponse)

  services.proto:45

  Two-sided unbounded streaming between server to client Both sides send the content of their own choice to the other

A service used to control reconnect server.

• rpc Start (ReconnectParams, Empty)

  test.proto:77

  message ReconnectParams

  messages.proto:159

  For reconnect interop test only. Client tells server what reconnection parameters it used.

  • int32 max_reconnect_backoff_ms = 1

• rpc Stop (Empty, ReconnectInfo)

  test.proto:78

  message ReconnectInfo

  messages.proto:166

  For reconnect interop test only. Server tells client whether its reconnects are following the spec and the reconnect backoffs it saw.

  • bool passed = 1

  • repeated int32 backoff_ms = 2

• rpc ReportScenario (ScenarioResult, Void)

  services.proto:74

  Report results of a QPS test benchmark scenario.

  message ScenarioResult

  control.proto:251

  Results of a single benchmark scenario.

  • optional Scenario scenario = 1

    Inputs used to run the scenario.

  • optional HistogramData latencies = 2

    Histograms from all clients merged into one histogram.

  • repeated ClientStats client_stats = 3

    Client stats for each client

  • repeated ServerStats server_stats = 4

    Server stats for each server

  • repeated int32 server_cores = 5

    Number of cores available to each server

  • optional ScenarioResultSummary summary = 6

    An after-the-fact computed summary

  • repeated bool client_success = 7

    Information on success or failure of each worker

  • repeated bool server_success = 8

  • repeated RequestResultCount request_results = 9

    Number of failed requests (one row per status code seen)

A simple service to test the various types of RPCs and experiment with performance with various types of payload.

• rpc EmptyCall (Empty, Empty)

  test.proto:30

  One empty request followed by one empty response.

• rpc UnaryCall (SimpleRequest, SimpleResponse)

  test.proto:33

  One request followed by one response.

• rpc CacheableUnaryCall (SimpleRequest, SimpleResponse)

  test.proto:38

  One request followed by one response. Response has cache control headers set such that a caching HTTP proxy (such as GFE) can satisfy subsequent requests.

• rpc StreamingOutputCall (StreamingOutputCallRequest, stream StreamingOutputCallResponse)

  test.proto:42

  One request followed by a sequence of responses (streamed download). The server returns the payload with client desired type and sizes.

• rpc StreamingInputCall (stream StreamingInputCallRequest, StreamingInputCallResponse)

  test.proto:47

  A sequence of requests followed by one response (streamed upload). The server returns the aggregated size of client payload as the result.

  message StreamingInputCallRequest

  messages.proto:97

  Client-streaming request.

  • optional Payload payload = 1

    Optional input payload sent along with the request.

  • optional BoolValue expect_compressed = 2

    Whether the server should expect this request to be compressed. This field is "nullable" in order to interoperate seamlessly with servers not able to implement the full compression tests by introspecting the call to verify the request's compression status.

  message StreamingInputCallResponse

  messages.proto:111

  Client-streaming response.

  • int32 aggregated_payload_size = 1

    Aggregated size of payloads received from the client.

• rpc FullDuplexCall (stream StreamingOutputCallRequest, stream StreamingOutputCallResponse)

  test.proto:53

  A sequence of requests with each request served by the server immediately. As one request could lead to multiple responses, this interface demonstrates the idea of full duplexing.

• rpc HalfDuplexCall (stream StreamingOutputCallRequest, stream StreamingOutputCallResponse)

  test.proto:60

  A sequence of requests followed by a sequence of responses. The server buffers all the client requests and then serves them in order. A stream of responses are returned to the client when the server starts with first request.

• rpc UnimplementedCall (Empty, Empty)

  test.proto:65

  The test server will not implement this method. It will be used to test the behavior when clients call unimplemented methods.

A simple service NOT implemented at servers so clients can test for that case.

• rpc UnimplementedCall (Empty, Empty)

  test.proto:72

  A call that no server should implement

• rpc RunServer (stream ServerArgs, stream ServerStatus)

  services.proto:55

  Start server with specified workload. First request sent specifies the ServerConfig followed by ServerStatus response. After that, a "Mark" can be sent anytime to request the latest stats. Closing the stream will initiate shutdown of the test server and once the shutdown has finished, the OK status is sent to terminate this RPC.

  message ServerArgs

  control.proto:159

  • oneof argtype

    • ServerConfig setup = 1

    • Mark mark = 2

  message ServerStatus

  control.proto:166

  • optional ServerStats stats = 1

  • int32 port = 2

    the port bound by the server

  • int32 cores = 3

    Number of cores available to the server

• rpc RunClient (stream ClientArgs, stream ClientStatus)

  services.proto:63

  Start client with specified workload. First request sent specifies the ClientConfig followed by ClientStatus response. After that, a "Mark" can be sent anytime to request the latest stats. Closing the stream will initiate shutdown of the test client and once the shutdown has finished, the OK status is sent to terminate this RPC.

  message ClientArgs

  control.proto:121

  • oneof argtype

    • ClientConfig setup = 1

    • Mark mark = 2

  message ClientStatus

  control.proto:113

  • optional ClientStats stats = 1

• rpc CoreCount (CoreRequest, CoreResponse)

  services.proto:66

  Just return the core count - unary call

  message CoreRequest

  control.proto:174

  (message has no fields)

  message CoreResponse

  control.proto:177

  • int32 cores = 1

    Number of cores available on the server

• rpc QuitWorker (Void, Void)

  services.proto:69

  Quit this worker

TODO(dgq): Go back to using well-known types once https://github.com/grpc/grpc/issues/6980 has been fixed. import "google/protobuf/wrappers.proto";

Used in: ResponseParameters, SimpleRequest, StreamingInputCallRequest

• bool value = 1

  The bool value.

Used in: PayloadConfig

• int32 req_size = 1

• int32 resp_size = 2

Used in: ClientConfig, ServerConfig

• string name = 1

• oneof value

  • string str_value = 2

  • int32 int_value = 3

Used in: ClientArgs, Scenario

• repeated string server_targets = 1

  List of targets to connect to. At least one target needs to be specified.

• ClientType client_type = 2

• optional SecurityParams security_params = 3

• int32 outstanding_rpcs_per_channel = 4

  How many concurrent RPCs to start for each channel. For synchronous client, use a separate thread for each outstanding RPC.

• int32 client_channels = 5

  Number of independent client channels to create. i-th channel will connect to server_target[i % server_targets.size()]

• int32 async_client_threads = 7

  Only for async client. Number of threads to use to start/manage RPCs.

• RpcType rpc_type = 8

• optional LoadParams load_params = 10

  The requested load for the entire client (aggregated over all the threads).

• optional PayloadConfig payload_config = 11

• optional HistogramParams histogram_params = 12

• repeated int32 core_list = 13

  Specify the cores we should run the client on, if desired

• int32 core_limit = 14

• string other_client_api = 15

  If we use an OTHER_CLIENT client_type, this string gives more detail

• repeated ChannelArg channel_args = 16

• int32 threads_per_cq = 17

  Number of threads that share each completion queue

• int32 messages_per_stream = 18

  Number of messages on a stream before it gets finished/restarted

Used in: ClientStatus, ScenarioResult

• optional HistogramData latencies = 1

  Latency histogram. Data points are in nanoseconds.

• double time_elapsed = 2

  See ServerStats for details.

• double time_user = 3

• double time_system = 4

• repeated RequestResultCount request_results = 5

  Number of failed requests (one row per status code seen)

• uint64 cq_poll_count = 6

  Number of polls called inside completion queue

Used in: ClientConfig

• SYNC_CLIENT = 0

  Many languages support a basic distinction between using sync or async client, and this allows the specification

• ASYNC_CLIENT = 1

• OTHER_CLIENT = 2

  used for some language-specific variants

Once an RPC finishes, immediately start a new one. No configuration parameters needed.

Used in: LoadParams

(message has no fields)

TODO (vpai): Fill this in once the details of complex, representative protos are decided

Used in: PayloadConfig

(message has no fields)

A protobuf representation for grpc status. This is used by test clients to specify a status that the server should attempt to return.

Used in: SimpleRequest, StreamingOutputCallRequest

• int32 code = 1

• string message = 2

An empty message that you can re-use to avoid defining duplicated empty messages in your project. A typical example is to use it as argument or the return value of a service API. For instance: service Foo { rpc Bar (grpc.testing.Empty) returns (grpc.testing.Empty) { }; };

Used as request type in: ReconnectService.Stop, TestService.EmptyCall, TestService.UnimplementedCall, UnimplementedService.UnimplementedCall

Used as response type in: ReconnectService.Start, TestService.EmptyCall, TestService.UnimplementedCall, UnimplementedService.UnimplementedCall

(message has no fields)

Histogram data based on grpc/support/histogram.c

Used in: ClientStats, ScenarioResult

• repeated uint32 bucket = 1

• double min_seen = 2

• double max_seen = 3

• double sum = 4

• double sum_of_squares = 5

• double count = 6

Histogram params based on grpc/support/histogram.c

Used in: ClientConfig

• double resolution = 1

  first bucket is [0, 1 + resolution)

• double max_possible = 2

  use enough buckets to allow this value

Used in: ClientConfig

• oneof load

  • ClosedLoopParams closed_loop = 1

  • PoissonParams poisson = 2

Request current stats

Used in: ClientArgs, ServerArgs

• bool reset = 1

  if true, the stats will be reset after taking their snapshot.

A block of data, to simply increase gRPC message size.

Used in: SimpleRequest, SimpleResponse, StreamingInputCallRequest, StreamingOutputCallRequest, StreamingOutputCallResponse

• PayloadType type = 1

  DEPRECATED, don't use. To be removed shortly. The type of data in body.

• bytes body = 2

  Primary contents of payload.

Used in: ClientConfig, ServerConfig

• oneof payload

  • ByteBufferParams bytebuf_params = 1

  • SimpleProtoParams simple_params = 2

  • ComplexProtoParams complex_params = 3

DEPRECATED, don't use. To be removed shortly. The type of payload that should be returned.

Used in: Payload, SimpleRequest, StreamingOutputCallRequest

• COMPRESSABLE = 0

  Compressable text format.

Parameters of poisson process distribution, which is a good representation of activity coming in from independent identical stationary sources.

Used in: LoadParams

• double offered_load = 1

  The rate of arrivals (a.k.a. lambda parameter of the exp distribution).

Used in: ClientStats, ScenarioResult

• int32 status_code = 1

• int64 count = 2

Configuration for a particular response.

Used in: StreamingOutputCallRequest

• int32 size = 1

  Desired payload sizes in responses from the server.

• int32 interval_us = 2

  Desired interval between consecutive responses in the response stream in microseconds.

• optional BoolValue compressed = 3

  Whether to request the server to compress the response. This field is "nullable" in order to interoperate seamlessly with clients not able to implement the full compression tests by introspecting the call to verify the response's compression status.

Used in: ClientConfig

• UNARY = 0

• STREAMING = 1

• STREAMING_FROM_CLIENT = 2

• STREAMING_FROM_SERVER = 3

• STREAMING_BOTH_WAYS = 4

A single performance scenario: input to qps_json_driver

Used in: ScenarioResult, Scenarios

• string name = 1

  Human readable name for this scenario

• optional ClientConfig client_config = 2

  Client configuration

• int32 num_clients = 3

  Number of clients to start for the test

• optional ServerConfig server_config = 4

  Server configuration

• int32 num_servers = 5

  Number of servers to start for the test

• int32 warmup_seconds = 6

  Warmup period, in seconds

• int32 benchmark_seconds = 7

  Benchmark time, in seconds

• int32 spawn_local_worker_count = 8

  Number of workers to spawn locally (usually zero)

Basic summary that can be computed from ClientStats and ServerStats once the scenario has finished.

Used in: ScenarioResult

• double qps = 1

  Total number of operations per second over all clients.

• double qps_per_server_core = 2

  QPS per one server core.

• double server_system_time = 3

  server load based on system_time (0.85 => 85%)

• double server_user_time = 4

  server load based on user_time (0.85 => 85%)

• double client_system_time = 5

  client load based on system_time (0.85 => 85%)

• double client_user_time = 6

  client load based on user_time (0.85 => 85%)

• double latency_50 = 7

  X% latency percentiles (in nanoseconds)

• double latency_90 = 8

• double latency_95 = 9

• double latency_99 = 10

• double latency_999 = 11

• double server_cpu_usage = 12

  server cpu usage percentage

• double successful_requests_per_second = 13

  Number of requests that succeeded/failed

• double failed_requests_per_second = 14

• double client_polls_per_request = 15

  Number of polls called inside completion queue per request

• double server_polls_per_request = 16

• double server_queries_per_cpu_sec = 17

  Queries per CPU-sec over all servers or clients

• double client_queries_per_cpu_sec = 18

A set of scenarios to be run with qps_json_driver

• repeated Scenario scenarios = 1

presence of SecurityParams implies use of TLS

Used in: ClientConfig, ServerConfig

• bool use_test_ca = 1

• string server_host_override = 2

• string cred_type = 3

Used in: Scenario, ServerArgs

• ServerType server_type = 1

• optional SecurityParams security_params = 2

• int32 port = 4

  Port on which to listen. Zero means pick unused port.

• int32 async_server_threads = 7

  Only for async server. Number of threads used to serve the requests.

• int32 core_limit = 8

  Specify the number of cores to limit server to, if desired

• optional PayloadConfig payload_config = 9

  payload config, used in generic server. Note this must NOT be used in proto (non-generic) servers. For proto servers, 'response sizes' must be configured from the 'response_size' field of the 'SimpleRequest' objects in RPC requests.

• repeated int32 core_list = 10

  Specify the cores we should run the server on, if desired

• string other_server_api = 11

  If we use an OTHER_SERVER client_type, this string gives more detail

• int32 threads_per_cq = 12

  Number of threads that share each completion queue

• int32 resource_quota_size = 1001

  Buffer pool size (no buffer pool specified if unset)

• repeated ChannelArg channel_args = 1002

Used in: ScenarioResult, ServerStatus

• double time_elapsed = 1

  wall clock time change in seconds since last reset

• double time_user = 2

  change in user time (in seconds) used by the server since last reset

• double time_system = 3

  change in server time (in seconds) used by the server process and all threads since last reset

• uint64 total_cpu_time = 4

  change in total cpu time of the server (data from proc/stat)

• uint64 idle_cpu_time = 5

  change in idle time of the server (data from proc/stat)

• uint64 cq_poll_count = 6

  Number of polls called inside completion queue

Used in: ServerConfig

• SYNC_SERVER = 0

• ASYNC_SERVER = 1

• ASYNC_GENERIC_SERVER = 2

• OTHER_SERVER = 3

  used for some language-specific variants

Used in: PayloadConfig

• int32 req_size = 1

• int32 resp_size = 2

Unary request.

Used as request type in: BenchmarkService.StreamingBothWays, BenchmarkService.StreamingCall, BenchmarkService.StreamingFromClient, BenchmarkService.StreamingFromServer, BenchmarkService.UnaryCall, TestService.CacheableUnaryCall, TestService.UnaryCall

• PayloadType response_type = 1

  DEPRECATED, don't use. To be removed shortly. Desired payload type in the response from the server. If response_type is RANDOM, server randomly chooses one from other formats.

• int32 response_size = 2

  Desired payload size in the response from the server.

• optional Payload payload = 3

  Optional input payload sent along with the request.

• bool fill_username = 4

  Whether SimpleResponse should include username.

• bool fill_oauth_scope = 5

  Whether SimpleResponse should include OAuth scope.

• optional BoolValue response_compressed = 6

  Whether to request the server to compress the response. This field is "nullable" in order to interoperate seamlessly with clients not able to implement the full compression tests by introspecting the call to verify the response's compression status.

• optional EchoStatus response_status = 7

  Whether server should return a given status

• optional BoolValue expect_compressed = 8

  Whether the server should expect this request to be compressed.

Unary response, as configured by the request.

Used as response type in: BenchmarkService.StreamingBothWays, BenchmarkService.StreamingCall, BenchmarkService.StreamingFromClient, BenchmarkService.StreamingFromServer, BenchmarkService.UnaryCall, TestService.CacheableUnaryCall, TestService.UnaryCall

• optional Payload payload = 1

  Payload to increase message size.

• string username = 2

  The user the request came from, for verifying authentication was successful when the client expected it.

• string oauth_scope = 3

  OAuth scope.

Server-streaming request.

Used as request type in: TestService.FullDuplexCall, TestService.HalfDuplexCall, TestService.StreamingOutputCall

• PayloadType response_type = 1

  DEPRECATED, don't use. To be removed shortly. Desired payload type in the response from the server. If response_type is RANDOM, the payload from each response in the stream might be of different types. This is to simulate a mixed type of payload stream.

• repeated ResponseParameters response_parameters = 2

  Configuration for each expected response message.

• optional Payload payload = 3

  Optional input payload sent along with the request.

• optional EchoStatus response_status = 7

  Whether server should return a given status

Server-streaming response, as configured by the request and parameters.

Used as response type in: TestService.FullDuplexCall, TestService.HalfDuplexCall, TestService.StreamingOutputCall

• optional Payload payload = 1

  Payload to increase response size.

Used as request type in: WorkerService.QuitWorker

Used as response type in: ReportQpsScenarioService.ReportScenario, WorkerService.QuitWorker

(message has no fields)