Health Checking Services

/**
 * Manages a health check service for gRPC servers.
 * Provides status management for individual services and overall server health.
 */
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4696")
public final class HealthStatusManager {
  
  /** The special service name representing all services on a gRPC server */
  public static final String SERVICE_NAME_ALL_SERVICES = "";
  
  /** Creates a new health service instance */
  public HealthStatusManager();
  
  /** 
   * Gets the health check service created in the constructor
   * @return BindableService that can be added to a gRPC server
   */
  public BindableService getHealthService();
  
  /**
   * Updates the status of the server
   * @param service The service name (use SERVICE_NAME_ALL_SERVICES for all services)
   * @param status The serving status to set
   */
  public void setStatus(String service, ServingStatus status);
  
  /**
   * Clears the health status record of a service
   * @param service The service name to clear
   */
  public void clearStatus(String service);
  
  /**
   * Marks all services as not serving and prevents future updates.
   * This is typically called during server shutdown.
   */
  public void enterTerminalState();
}

import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.protobuf.services.HealthStatusManager;
import io.grpc.health.v1.HealthCheckResponse.ServingStatus;

// Create health status manager
HealthStatusManager healthManager = new HealthStatusManager();

// Add health service to server
Server server = ServerBuilder.forPort(8080)
    .addService(healthManager.getHealthService())
    .addService(new MyCustomService())
    .build();

// Set overall server status
healthManager.setStatus(
    HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
    ServingStatus.SERVING
);

// Set specific service status
healthManager.setStatus("com.example.MyService", ServingStatus.SERVING);

// During shutdown
healthManager.enterTerminalState();
server.shutdown();

// Global server health (affects all services)
healthManager.setStatus(
    HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
    ServingStatus.SERVING
);

// Individual service health
healthManager.setStatus("user.service", ServingStatus.SERVING);
healthManager.setStatus("payment.service", ServingStatus.NOT_SERVING);

// Clear a service's health status (removes from health reports)
healthManager.clearStatus("payment.service");

import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.protobuf.services.HealthStatusManager;

public class HealthAwareServer {
    private final HealthStatusManager healthManager;
    private final Server server;
    
    public HealthAwareServer(int port) {
        this.healthManager = new HealthStatusManager();
        this.server = ServerBuilder.forPort(port)
            .addService(healthManager.getHealthService())
            .addService(new MyBusinessService())
            .build();
    }
    
    public void start() throws IOException {
        server.start();
        
        // Initially mark as serving
        healthManager.setStatus(
            HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
            ServingStatus.SERVING
        );
    }
    
    public void gracefulShutdown() {
        // Mark as not serving to drain traffic
        healthManager.setStatus(
            HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
            ServingStatus.NOT_SERVING
        );
        
        // Wait for existing requests to complete
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        
        // Enter terminal state and shutdown
        healthManager.enterTerminalState();
        server.shutdown();
    }
}

/** 
 * Serving status enumeration for health checking
 */
public enum ServingStatus {
  /** Service is healthy and ready to serve requests */
  SERVING,
  /** Service is not healthy and should not receive requests */
  NOT_SERVING,
  /** Service status is unknown (used for services not explicitly registered) */
  SERVICE_UNKNOWN
}