doc/health-checking.md

   1 GRPC Health Checking Protocol
   2 ================================
   3
   4 Health checks are used to probe whether the server is able to handle rpcs. The
   5 client-to-server health checking can happen from point to point or via some
   6 control system. A server may choose to reply “unhealthy” because it
   7 is not ready to take requests, it is shutting down or some other reason.
   8 The client can act accordingly if the response is not received within some time
   9 window or the response says unhealthy in it.
  10
  11
  12 A GRPC service is used as the health checking mechanism for both simple
  13 client-to-server scenario and other control systems such as load-balancing.
  14 Being a high
  15 level service provides some benefits. Firstly, since it is a GRPC service
  16 itself, doing a health check is in the same format as a normal rpc. Secondly,
  17 it has rich semantics such as per-service health status. Thirdly, as a GRPC
  18 service, it is able reuse all the existing billing, quota infrastructure, etc,
  19 and thus the server has full control over the access of the health checking
  20 service.
  21
  22 ## Service Definition
  23
  24 The server should export a service defined in the following proto:
  25
  26 ```
  27 syntax = "proto3";
  28
  29 package grpc.health.v1;
  30
  31 message HealthCheckRequest {
  32   string service = 1;
  33 }
  34
  35 message HealthCheckResponse {
  36   enum ServingStatus {
  37     UNKNOWN = 0;
  38     SERVING = 1;
  39     NOT_SERVING = 2;
  40   }
  41   ServingStatus status = 1;
  42 }
  43
  44 service Health {
  45   rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  46 }
  47 ```
  48
  49 A client can query the server’s health status by calling the `Check` method, and
  50 a deadline should be set on the rpc. The client can optionally set the service
  51 name it wants to query for health status. The suggested format of service name
  52 is `package_names.ServiceName`, such as `grpc.health.v1.Health`.
  53
  54 The server should register all the services manually and set
  55 the individual status, including an empty service name and its status. For each
  56 request received, if the service name can be found in the registry,
  57 a response must be sent back with an `OK` status and the status field should be
  58 set to `SERVING` or `NOT_SERVING` accordingly. If the service name is not
  59 registered, the server returns a `NOT_FOUND` GRPC status.
  60
  61 The server should use an empty string as the key for server's
  62 overall health status, so that a client not interested in a specific service can
  63 query the server's status with an empty request. The server can just do exact
  64 matching of the service name without support of any kind of wildcard matching.
  65 However, the service owner has the freedom to implement more complicated
  66 matching semantics that both the client and server agree upon.
  67
  68 A client can declare the server as unhealthy if the rpc is not finished after
  69 some amount of time. The client should be able to handle the case where server
  70 does not have the Health service.