Confused about health checking protocol

Question

I have read below doc, source code and issue:

• https://github.com/grpc/grpc/blob/master/doc/health-checking.md
• https://github.com/grpc/grpc-node/blob/master/packages/grpc-health-check/test/health_test.js
• https://github.com/grpc/grpc/issues/10428

I provide an example and try to explain:

// Import package
let health = require('grpc-health-check');

// Define service status map. Key is the service name, value is the corresponding status.
// By convention, the empty string "" key represents that status of the entire server.
const statusMap = {
  "ServiceFoo": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.SERVING,
  "ServiceBar": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.NOT_SERVING,
  "": proto.grpc.health.v1.HealthCheckResponse.ServingStatus.NOT_SERVING,
};

// Construct the service implementation
let healthImpl = new health.Implementation(statusMap);

// Add the service and implementation to your pre-existing gRPC-node server
server.addService(health.service, healthImpl);

I am not clear about the following points:

1. Does the service name in statusMap need to be the same as the service name in the protocol buffers file? Or the service name can be arbitrarily specified. If so, how does the service name map to the service defined in the protocol buffers?

From the health checking protocol:

The server should register all the services manually and set the individual status

2. Why do we need to register manually? If the service code can be generated, why doesn't grpc help us automatically register the service name in statusMap? (Imagine setting the status of 100 services one by one)

3. The service status is hard code and cannot be changed at application runtime. If my service is unavailable at runtime for some reason such as misconfiguration, downstream service is not available, but the status of the service is always serving(because it's hard code), if so, what is the meaning of the health check?

For RESTful API, we can provide a /health-check or /ping API to check that the entire server is running normally.

Answer 1

Regarding the service names, the first linked document says this:

The suggested format of service name is package_names.ServiceName, such as grpc.health.v1.Health.

This does correspond to the package names and service name defined in the Protobuf definition.

The services need to be registered "manually" because the status is determined at the application level, which the grpc library does not know about, and a registered service name is only meaningful along with the corresponding status. In addition, the naming format mentioned above is just a convention; the health check service user is not constrained to it, and the actual services on the server are not constrained to use the standard /package_names.ServiceName/MethodName method naming scheme either.

Regarding the third point, the service status should not be hardcoded, and can be changed at runtime. The HealthImplementation class used in the code in the question has a setStatus method that can be used to update the status.

Also, as mentioned in a comment in the code in the question,

By convention, the empty string "" key represents that status of the entire server.

That can be used as the equivalent of the /health-check or /ping REST APIs.