traffic_config.proto

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package distbench;

import "joint_distribution.proto";

// Specifies how many instances there are of each service, their organization,
// and protocol-specific options.
//
// A service can be modeled as a 1D, 2D, or 3D grid of instances, in which
// case the "count" field is optional.
// The product of the x/y/z sizes (if present) must be equal to the count
// field (if present). These rank of each instance of the service is used
// by the following fanout_filter values:
// same_x, same_y, same_z, same_xy, same_yz, same xz, same_xyz, ring_x, ring_y
// ring_z, linear_x, linear_y, linear_z
//
// For services that do not specify x/y/z sizes, the name assigned to individual
// instances will be "$name/$instance_number", e.g. "search_leaf/0"
// For services that specify only x_size the name of an individual instance
// will be "$name/$x_rank", e.g. "search_leaf/0"
// For services that specify y_size the name of an individual instance
// will be "$name/$x_rank/$y_rank", e.g. "search_leaf/0/2"
// For services thatspecify z_size the name of an individual instance
// will be "$name/$x_rank/$y_rank/$z_rank", e.g. "search_leaf/0/2/1"
message ServiceSpec {
  optional string name = 1;
  optional int32 count = 2;
  optional string protocol_driver_options_name = 3;
  optional int32 x_size = 4 [default = 1];
  // if x_size is not set, then y_size must not be set.
  optional int32 y_size = 5 [default = 1];
  // if y_size is not set, then z_size must not be set.
  optional int32 z_size = 6 [default = 1];

  repeated MultiServerChannel multi_server_channels = 7;
}

// Server channels allow experiments with dynamic client-side load balancing
// strategies. A channel can refer to one or more servers, with a specific
// configuration for how to select a subset of the available servers.
message MultiServerChannel {
  optional string name = 1;
  repeated NamedSetting channel_settings = 2;

  // The server instances that make up this channel can either be precomputed
  // or dynamically computed. Any instances specified here are included
  // regardless of whether or not they satisfy the constraints below:
  repeated int32 selected_instances = 3 [packed = true];

  optional ConstraintList constraints = 4;
}

message ConstraintList {
  // A node matches only if it satisfies all constraint sets (logical AND):
  repeated ConstraintSet constraint_sets = 1;
}

message ConstraintSet {
  // A node satisifies this constraint set if it matches any of its
  // individual constraints (logical OR):
  repeated Constraint constraints = 1;
}

message Constraint {
  enum Relation {
    UNKNOWN = 0;
    EQUAL = 1;
    NOT_EQUAL = 2;
    MODULO_EQUAL = 3;
    MODULO_NOT_EQUAL = 4;
  }

  // Attributes of each server instance include the GridIndex values (x/y/z) as
  // well as any attributes of the underlying node that are inherited from the
  // NodeManager instance.
  optional string attribute_name = 1;
  repeated string string_values = 2;
  repeated int64  int64_values = 3 [packed = true];
  optional Relation relation = 4;
  optional int64  modulus = 5;
}

// Specifies how multiple services may be co-located on the same machine.
// By default each service is allocated a separate machine, if not mentioned.
message ServiceBundle {
  repeated string services = 1;
}

// Defines how to construct a pool of protobufs to be used as requests or
// responses.
message PayloadSpec {
  optional string name = 1;
  repeated string attributes = 2;
  optional string size_distribution_name = 3;
  optional int64 size = 4;  // Special case to specify a fixed size.
}

message RpcSpec {
  optional string name = 1;
  repeated string client = 2;
  optional string server = 3;
  optional string request_payload_name = 4;
  optional string response_payload_name = 5;
  optional string fanout_filter = 6 [default = "all"];
  optional int32 tracing_interval = 7;
  optional string distribution_config_name = 8;

  // If a server channel is specified the protocol driver will decide how
  // to pick the specific server node(s) to target.
  optional string multi_server_channel_name = 9;
}

message Iterations {
  optional int32 max_iteration_count = 1;
  optional int32 max_duration_us = 2;
  optional int64 max_parallel_iterations = 3 [default = 1];
  optional int64 open_loop_interval_ns = 4;
  optional string open_loop_interval_distribution = 5 [default = "constant"];
  // Marks RPCs triggered by the first N iterations as warmup RPCs,
  // which can be discarded by downstream analysis tools.
  optional int64 warmup_iterations = 6 [default = 0];
}

message ActivityConfig {
  optional string name = 1;
  repeated NamedSetting activity_settings = 2;
}

message RpcReplayTraceRecord {
  enum TimingMode {
    UNKNOWN = 0;
    RELATIVE_TO_TRAFFIC_START = 1;
    RELATIVE_TO_TRACE_START = 2;
    RELATIVE_TO_PRIOR_RPC_START = 3;
    RELATIVE_TO_PRIOR_RPC_END = 4;
  }
  optional int64 timing_ns = 1;
  optional TimingMode timing_mode = 2;

  // If timing mode is RELATIVE_TO_PRIOR_RPC_START or RELATIVE_TO_PRIOR_RPC_END
  // this specifies the specific RPC(s) to use for timing. If this is not
  // present then the immediately preceding RPC will be used. Must be
  // non-negative, and less than the current index.
  repeated int32 prior_rpc_distances = 3 [packed = true];

  // Replay RPCs do not have server-side handling via action lists,
  // but can be grouped into classes for statistics processing purposes.
  optional int32 rpc_class = 4;

  // The client and server instances specify which service instances are the
  // source and target of the given RPC.

  // If the client instance is not specified, then all instances will
  // Send this RPC.
  optional int32 client_instance = 5;

  // An RPC can either refer to a specific server instance, or to a specific
  // multiserver channel by specifying the index into
  // the multiserver_channel_names repeated field of the RpcReplayTrace.
  optional int32 server_instance = 6;
  optional int32 multi_server_channel_name_index = 7;

  optional int32 request_size = 8;
  optional int32 response_size = 9;
  optional int64 server_processing_time_ns = 10;
}

message RpcReplayTrace {
  optional string name = 1;
  optional string client = 2;
  optional string server = 3;
  repeated string multiserver_channel_names = 4;
  optional RpcReplayTraceRecord defaults = 5;
  repeated RpcReplayTraceRecord records = 6;
}

message Action {
  optional string name = 1;
  repeated string dependencies = 2;
  optional string delay_distribution_name = 13;
  optional Iterations iterations = 3;
  oneof action {
    // If none of these is set, the action is a NOP, but may still have
    // side-effects, particularly sending a response.
    string rpc_name = 4;
    string action_list_name = 5;
    string activity_config_name = 6;
    string rpc_replay_trace_name = 7;
  }
  optional bool send_response_when_done = 10;
  optional bool cancel_traffic_when_done = 11 [default = false];
  repeated string predicates = 12;

  // For an RPC action this chooses an alternative payload:
  optional string request_payload_override = 14;

  // For an action that sets send_response_when_done, this chooses
  // an alternative payload:
  optional string response_payload_override = 15;
}

message ActionList {
  optional string name = 1;
  repeated string action_names = 2;
  // If more than max_rpc_samples rpcs are performed then distbench will
  // choose the samples to retain via reservoir sampling.
  // Setting this to zero will retain all samples, but may hurt performance.
  optional int64 max_rpc_samples = 3 [default = 0];

  // Each time an ActionList is run any predicates that it defines will be
  // assigned true or false values based on their associated probability.
  // Execution of each action in the list can then be predicated upon
  // the values of these named predicates or their complement
  // (these are expressed as "name" or "!name").
  // If an action specifies a predicate that evaluates to false it will be
  // skipped, and any actions that depend on skipped actions will also be
  // skipped.
  map<string, float> predicate_probabilities = 4;
}

message NamedSetting {
  optional string name = 1;
  optional string string_value = 2;
  optional int64  int64_value = 3;
}

message ProtocolDriverOptions {
  optional string name = 1;
  optional string protocol_name = 2;
  optional string netdev_name = 3;
  repeated NamedSetting server_settings = 4;
  repeated NamedSetting client_settings = 5;
  optional int32 ip_version = 6 [default = 0];
}

message OverloadLimits {
  optional int64 max_threads = 1 [default = 1000];
  optional int64 max_pending_rpcs = 2 [default = 1000000];
}

message DistributedSystemDescription {
  optional string name = 9;

  // Attributes are free-form metadata-only. They do not affect the operation of
  // the distbench nodes in any way. They serve to document the system settings
  // that were used to generate a test, or that were in effect when the test
  // was run.
  map<string, string> attributes = 10;

  repeated ServiceSpec services = 1;
  map<string, ConstraintList> service_constraints = 15;
  map<string, ServiceBundle> node_service_bundles = 2;

  // In order to provide the users with an easy way of creating
  // text_protos, 'repeated' fields are used instead of 'maps'.
  repeated PayloadSpec payload_descriptions = 3;
  repeated RpcSpec rpc_descriptions = 4;
  repeated ActivityConfig activity_configs = 11;
  repeated Action actions = 5;
  repeated ActionList action_lists = 6;

  optional string default_protocol = 7 [default = "grpc"];
  repeated ProtocolDriverOptions protocol_driver_options = 8;
  repeated DistributionConfig distribution_config = 12;
  repeated DistributionConfig delay_distribution_configs = 16;
  repeated DistributionConfig size_distribution_configs = 17;

  optional OverloadLimits overload_limits = 13;

  repeated RpcReplayTrace rpc_replay_traces = 14;

  // If set to true then when an action has a delay distribution
  // instead of delaying the first iteration of that action by sleeping in
  // parallel with any other actions,
  // the distbench engine will burn CPU in the handling thread for the given
  // time. This includes tracking the time that the thread is not scheduled in
  // order to simulate doing real work.
  optional bool delay_actions_by_spinning = 18 [default = false];
}