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