package grpc.lb.v1

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc BalanceLoad (stream LoadBalanceRequest, stream LoadBalanceResponse)

  load_balancer.proto:33

  Bidirectional rpc to get a list of servers.

  message LoadBalanceRequest

  load_balancer.proto:36

  • oneof load_balance_request_type

    • InitialLoadBalanceRequest initial_request = 1

      This message should be sent on the first request to the load balancer.

    • ClientStats client_stats = 2

      The client stats should be periodically reported to the load balancer based on the duration defined in the InitialLoadBalanceResponse.

  message LoadBalanceResponse

  load_balancer.proto:89

  • oneof load_balance_response_type

    • InitialLoadBalanceResponse initial_response = 1

      This message should be sent on the first response to the client.

    • ServerList server_list = 2

      Contains the list of servers selected by the load balancer. The client should send requests to these servers in the specified order.

    • FallbackResponse fallback_response = 3

      If this field is set, then the client should eagerly enter fallback mode (even if there are existing, healthy connections to backends).

The LoadReporter service.

• rpc ReportLoad (stream LoadReportRequest, stream LoadReportResponse)

  load_reporter.proto:24

  Report load from server to lb.

  message LoadReportRequest

  load_reporter.proto:29

  • optional InitialLoadReportRequest initial_request = 1

    This message should be sent on the first request to the gRPC server.

  message LoadReportResponse

  load_reporter.proto:49

  • optional InitialLoadReportResponse initial_response = 1

    This message should be sent on the first response to the load balancer.

  • optional LoadBalancingFeedback load_balancing_feedback = 2

    Reports server-wide statistics for load balancing. This should be reported with every response.

  • repeated Load load = 3

    A load report for each <tag, user_id> tuple. This could be considered to be a multimap indexed by <tag, user_id>. It is not strictly necessary to aggregate all entries into one entry per <tag, user_id> tuple, although it is preferred to do so.

Used in: Load

• string metric_name = 1

  Name of the metric; may be empty.

• int64 num_calls_finished_with_metric = 2

  Number of calls that finished and included this metric.

• double total_metric_value = 3

  Sum of metric values across all calls that finished with this metric.

Contains client level statistics that are useful to load balancing. Each count except the timestamp should be reset to zero after reporting the stats.

Used in: LoadBalanceRequest

• optional google.protobuf.Timestamp timestamp = 1

  The timestamp of generating the report.

• int64 num_calls_started = 2

  The total number of RPCs that started.

• int64 num_calls_finished = 3

  The total number of RPCs that finished.

• int64 num_calls_finished_with_client_failed_to_send = 6

  The total number of RPCs that failed to reach a server except dropped RPCs.

• int64 num_calls_finished_known_received = 7

  The total number of RPCs that finished and are known to have been received by a server.

• repeated ClientStatsPerToken calls_finished_with_drop = 8

  The list of dropped calls.

Contains the number of calls finished for a particular load balance token.

Used in: ClientStats

• string load_balance_token = 1

  See Server.load_balance_token.

• int64 num_calls = 2

  The total number of RPCs that finished associated with the token.

Used in: LoadBalanceResponse

(message has no fields)

Used in: LoadBalanceRequest

• string name = 1

  The name of the load balanced service (e.g., service.googleapis.com). Its length should be less than 256 bytes. The name might include a port number. How to handle the port number is up to the balancer.

Used in: LoadBalanceResponse

• optional google.protobuf.Duration client_stats_report_interval = 2

  This interval defines how often the client should send the client stats to the load balancer. Stats should only be reported when the duration is positive.

Used in: LoadReportRequest

• string load_balanced_hostname = 1

  The hostname this load reporter client is requesting load for.

• bytes load_key = 2

  Additional information to disambiguate orphaned load: load that should have gone to this load reporter client, but was not able to be sent since the load reporter client has disconnected. load_key is sent in orphaned load reports; see Load.load_key.

• optional google.protobuf.Duration load_report_interval = 3

  This interval defines how often the server should send load reports to the load balancer.

Used in: LoadReportResponse

• string load_balancer_id = 1

  Initial response returns the Load balancer ID. This must be plain text (printable ASCII).

• InitialLoadReportResponse.ImplementationIdentifier implementation_id = 2

  Optional identifier of this implementation of the load reporting server.

• int64 server_version = 3

  Optional server_version should be a value that is modified (and monotonically increased) when changes are made to the server implementation.

Used in: InitialLoadReportResponse

• IMPL_UNSPECIFIED = 0

• CPP = 1

  Standard Google C++ implementation.

• JAVA = 2

  Standard Google Java implementation.

• GO = 3

  Standard Google Go implementation.

Used in: LoadReportResponse

• string load_balance_tag = 1

  The (plain text) tag used by the calls covered by this load report. The tag is that part of the load balancer token after removing the load balancer id. Empty is equivalent to non-existent tag.

• string user_id = 3

  The user identity authenticated by the calls covered by this load report. Empty is equivalent to no known user_id.

• bytes client_ip_address = 15

  IP address of the client that sent these requests, serialized in network-byte-order. It may either be an IPv4 or IPv6 address.

• int64 num_calls_started = 4

  The number of calls started (since the last report) with the given tag and user_id.

• oneof in_progress_report

  Indicates whether this load report is an in-progress load report in which num_calls_in_progress is the only valid entry. If in_progress_report is not set, num_calls_in_progress will be ignored. If in_progress_report is set, fields other than num_calls_in_progress and orphaned_load will be ignored. TODO(juanlishen): A Load is either an in_progress_report or not. We should make this explicit in hierarchy. From the log, I see in_progress_report_ has a random num_calls_in_progress_ when not set, which might lead to bug when the balancer process the load report.

  • int64 num_calls_in_progress = 5

    The number of calls in progress (instantaneously) per load balancer id.

• int64 num_calls_finished_without_error = 6

  The following values are counts or totals of call statistics that finished with the given tag and user_id.

  Calls with status OK.

• int64 num_calls_finished_with_error = 7

  Calls with status non-OK.

• int64 num_calls_finished_with_server_error = 16

  Calls that finished with a status that maps to HTTP 5XX (see googleapis/google/rpc/code.proto). Note that this is a subset of num_calls_finished_with_error.

• int64 total_bytes_sent = 8

  Totals are from calls that with _and_ without error.

• int64 total_bytes_received = 9

• optional google.protobuf.Duration total_latency = 10

• repeated CallMetricData metric_data = 11

  Optional metrics reported for the call(s). Requires that metric_name is unique.

• oneof orphaned_load

  The following two fields are used for reporting orphaned load: load that could not be reported to the originating balancer either since the balancer is no longer connected or because the frontend sent an invalid token. These fields must not be set with normal (unorphaned) load reports.

  • bytes load_key = 12

    Load_key is the load_key from the initial_request from the originating balancer.

  • bool load_key_unknown = 13

    If true then this load report is for calls that had an invalid token; the user is probably abusing the gRPC protocol. TODO(yankaiz): Rename load_key_unknown.

  • OrphanedLoadIdentifier orphaned_load_identifier = 14

    load_key and balancer_id are included in order to identify orphaned load from different origins.

Used in: LoadReportResponse

• float server_utilization = 1

  Reports the current utilization of the server (typical range [0.0 - 1.0]).

• float calls_per_second = 2

  The total rate of calls handled by this server (including errors).

• float errors_per_second = 3

  The total rate of error responses sent by this server.

Used in: Load

• bytes load_key = 1

  The load_key from the initial_request from the originating balancer.

• string load_balancer_id = 2

  The unique ID generated by LoadReporter to identify balancers. Here it distinguishes orphaned load with a same load_key.

Contains server information. When the drop field is not true, use the other fields.

Used in: ServerList

• bytes ip_address = 1

  A resolved address for the server, serialized in network-byte-order. It may either be an IPv4 or IPv6 address.

• int32 port = 2

  A resolved port number for the server.

• string load_balance_token = 3

  An opaque but printable token for load reporting. The client must include the token of the picked server into the initial metadata when it starts a call to that server. The token is used by the server to verify the request and to allow the server to report load to the gRPC LB system. The token is also used in client stats for reporting dropped calls. Its length can be variable but must be less than 50 bytes.

• bool drop = 4

  Indicates whether this particular request should be dropped by the client. If the request is dropped, there will be a corresponding entry in ClientStats.calls_finished_with_drop.

Used in: LoadBalanceResponse

• repeated Server servers = 1

  Contains a list of servers selected by the load balancer. The list will be updated when server resolutions change or as needed to balance load across more servers. The client should consume the server list in order unless instructed otherwise via the client_config.