improve comments on benchmark protos

3 files changed, 35 insertions, 9 deletions

diff --git a/test/proto/benchmarks/control.proto b/test/proto/benchmarks/control.proto
index 962bd2f8cc..42a5dd0a85 100644
--- a/test/proto/benchmarks/control.proto
+++ b/test/proto/benchmarks/control.proto
@@ -49,7 +49,10 @@ enum RpcType {
   STREAMING = 1;
 }
 
+// Parameters of poisson process distribution, which is a good representation
+// of activity coming in from independent identical stationary sources.
 message PoissonParams {
+  // The rate of arrivals (a.k.a. lambda parameter of the exp distribution).
   double offered_load = 1;
 }
 
@@ -67,6 +70,8 @@ message ParetoParams {
   double alpha = 2;
 }
 
+// Once an RPC finishes, immediately start a new one.
+// No configuration parameters needed.
 message ClosedLoopParams {
 }
 
@@ -87,14 +92,20 @@ message SecurityParams {
 }
 
 message ClientConfig {
+  // List of targets to connect to. At least one target needs to be specified.
   repeated string server_targets = 1;
   ClientType client_type = 2;
   SecurityParams security_params = 3;
+  // How many concurrent RPCs to start for each channel.
+  // For synchronous client, use a separate thread for each outstanding RPC.
   int32 outstanding_rpcs_per_channel = 4;
+  // Number of independent client channels to create.
+  // i-th channel will connect to server_target[i % server_targets.size()]
   int32 client_channels = 5;
-  // only for async client:
+  // Only for async client. Number of threads to use to start/manage RPCs.
   int32 async_client_threads = 7;
   RpcType rpc_type = 8;
+  // The requested load for the entire client (aggregated over all the threads).
   LoadParams load_params = 10;
   PayloadConfig payload_config = 11;
   HistogramParams histogram_params = 12;
@@ -106,6 +117,7 @@ message ClientStatus {
 
 // Request current stats
 message Mark {
+  // if true, the stats will be reset after taking their snapshot.
   bool reset = 1;
 }
 
@@ -119,11 +131,13 @@ message ClientArgs {
 message ServerConfig {
   ServerType server_type = 1;
   SecurityParams security_params = 2;
+  // Host on which to listen.
   string host = 3;
+  // Port on which to listen. Zero means pick unused port.
   int32 port = 4;
-  // only for async server
+  // Only for async server. Number of threads used to serve the requests.
   int32 async_server_threads = 7;
-  // restrict core usage
+  // restrict core usage, currently unused
   int32 core_limit = 8;
   PayloadConfig payload_config = 9;
 }
@@ -137,6 +151,8 @@ message ServerArgs {
 
 message ServerStatus {
   ServerStats stats = 1;
+  // the port bound by the server
   int32 port = 2;
+  // Number of cores on the server. See gpr_cpu_num_cores.
   int32 cores = 3;
 }
diff --git a/test/proto/benchmarks/services.proto b/test/proto/benchmarks/services.proto
index 4c2cbabdf8..ff295ed970 100644
--- a/test/proto/benchmarks/services.proto
+++ b/test/proto/benchmarks/services.proto
@@ -47,9 +47,19 @@ service BenchmarkService {
 }
 
 service WorkerService {
-  // Start server with specified workload
+  // 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.
   rpc RunServer(stream ServerArgs) returns (stream ServerStatus);
 
-  // Start client with specified workload
+  // 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.
   rpc RunClient(stream ClientArgs) returns (stream ClientStatus);
 }
diff --git a/test/proto/benchmarks/stats.proto b/test/proto/benchmarks/stats.proto
index 194db47caa..6b045b3119 100644
--- a/test/proto/benchmarks/stats.proto
+++ b/test/proto/benchmarks/stats.proto
@@ -32,14 +32,14 @@ syntax = "proto3";
 package grpc.testing;
 
 message ServerStats {
-  // wall clock time change since last reset
+  // wall clock time change in seconds since last reset
   double time_elapsed = 1;
 
-  // change in user time used by the server since last reset
+  // change in user time (in seconds) used by the server since last reset
   double time_user = 2;
 
-  // change in server time used by the server process and all threads since
-  // last reset
+  // change in server time (in seconds) used by the server process and all
+  // threads since last reset
   double time_system = 3;
 }