0
# Health Checking Services
1

2
Server health status management for load balancer health checks and service monitoring. The health checking service provides both individual service status reporting and overall server health management.
3

4
## Capabilities
5

6
### HealthStatusManager
7

8
Main class for managing health check services and status reporting.
9

10
```java { .api }
11
/**
12
 * Manages a health check service for gRPC servers.
13
 * Provides status management for individual services and overall server health.
14
 */
15
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4696")
16
public final class HealthStatusManager {
17
  
18
  /** The special service name representing all services on a gRPC server */
19
  public static final String SERVICE_NAME_ALL_SERVICES = "";
20
  
21
  /** Creates a new health service instance */
22
  public HealthStatusManager();
23
  
24
  /** 
25
   * Gets the health check service created in the constructor
26
   * @return BindableService that can be added to a gRPC server
27
   */
28
  public BindableService getHealthService();
29
  
30
  /**
31
   * Updates the status of the server
32
   * @param service The service name (use SERVICE_NAME_ALL_SERVICES for all services)
33
   * @param status The serving status to set
34
   */
35
  public void setStatus(String service, ServingStatus status);
36
  
37
  /**
38
   * Clears the health status record of a service
39
   * @param service The service name to clear
40
   */
41
  public void clearStatus(String service);
42
  
43
  /**
44
   * Marks all services as not serving and prevents future updates.
45
   * This is typically called during server shutdown.
46
   */
47
  public void enterTerminalState();
48
}
49
```
50

51
**Usage Examples:**
52

53
```java
54
import io.grpc.Server;
55
import io.grpc.ServerBuilder;
56
import io.grpc.protobuf.services.HealthStatusManager;
57
import io.grpc.health.v1.HealthCheckResponse.ServingStatus;
58

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

62
// Add health service to server
63
Server server = ServerBuilder.forPort(8080)
64
    .addService(healthManager.getHealthService())
65
    .addService(new MyCustomService())
66
    .build();
67

68
// Set overall server status
69
healthManager.setStatus(
70
    HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
71
    ServingStatus.SERVING
72
);
73

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

77
// During shutdown
78
healthManager.enterTerminalState();
79
server.shutdown();
80
```
81

82
### Service Status Management
83

84
Health checking supports both global server status and individual service status reporting.
85

86
```java
87
// Global server health (affects all services)
88
healthManager.setStatus(
89
    HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
90
    ServingStatus.SERVING
91
);
92

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

97
// Clear a service's health status (removes from health reports)
98
healthManager.clearStatus("payment.service");
99
```
100

101
### Integration with Load Balancers
102

103
Health checking services work with gRPC-aware load balancers for automatic traffic routing:
104

105
```java
106
import io.grpc.Server;
107
import io.grpc.ServerBuilder;
108
import io.grpc.protobuf.services.HealthStatusManager;
109

110
public class HealthAwareServer {
111
    private final HealthStatusManager healthManager;
112
    private final Server server;
113
    
114
    public HealthAwareServer(int port) {
115
        this.healthManager = new HealthStatusManager();
116
        this.server = ServerBuilder.forPort(port)
117
            .addService(healthManager.getHealthService())
118
            .addService(new MyBusinessService())
119
            .build();
120
    }
121
    
122
    public void start() throws IOException {
123
        server.start();
124
        
125
        // Initially mark as serving
126
        healthManager.setStatus(
127
            HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
128
            ServingStatus.SERVING
129
        );
130
    }
131
    
132
    public void gracefulShutdown() {
133
        // Mark as not serving to drain traffic
134
        healthManager.setStatus(
135
            HealthStatusManager.SERVICE_NAME_ALL_SERVICES, 
136
            ServingStatus.NOT_SERVING
137
        );
138
        
139
        // Wait for existing requests to complete
140
        try {
141
            Thread.sleep(5000);
142
        } catch (InterruptedException e) {
143
            Thread.currentThread().interrupt();
144
        }
145
        
146
        // Enter terminal state and shutdown
147
        healthManager.enterTerminalState();
148
        server.shutdown();
149
    }
150
}
151
```
152

153
## Types
154

155
```java { .api }
156
/** 
157
 * Serving status enumeration for health checking
158
 */
159
public enum ServingStatus {
160
  /** Service is healthy and ready to serve requests */
161
  SERVING,
162
  /** Service is not healthy and should not receive requests */
163
  NOT_SERVING,
164
  /** Service status is unknown (used for services not explicitly registered) */
165
  SERVICE_UNKNOWN
166
}
167
```