0
# gRPC Services
1

2
gRPC Services is a comprehensive Java library that provides essential service utilities and implementations for gRPC applications. It includes health checking, server reflection, channelz observability, binary logging, and metrics recording capabilities for building production-ready gRPC servers.
3

4
## Package Information
5

6
- **Package Name**: io.grpc:grpc-services
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml` or `build.gradle`
10

11
**Maven:**
12
```xml
13
<dependency>
14
    <groupId>io.grpc</groupId>
15
    <artifactId>grpc-services</artifactId>
16
    <version>1.73.0</version>
17
</dependency>
18
```
19

20
**Gradle:**
21
```gradle
22
implementation 'io.grpc:grpc-services:1.73.0'
23
```
24

25
## Core Imports
26

27
```java
28
import io.grpc.protobuf.services.HealthStatusManager;
29
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
30
import io.grpc.protobuf.services.ChannelzService;
31
import io.grpc.protobuf.services.BinaryLogs;
32
import io.grpc.services.CallMetricRecorder;
33
import io.grpc.services.MetricRecorder;
34
import io.grpc.services.AdminInterface;
35
```
36

37
## Basic Usage
38

39
```java
40
import io.grpc.Server;
41
import io.grpc.ServerBuilder;
42
import io.grpc.protobuf.services.HealthStatusManager;
43
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
44
import io.grpc.services.AdminInterface;
45

46
// Create a gRPC server with health checking and reflection
47
HealthStatusManager healthManager = new HealthStatusManager();
48

49
Server server = ServerBuilder.forPort(8080)
50
    .addService(healthManager.getHealthService())
51
    .addService(ProtoReflectionServiceV1.newInstance())
52
    .addServices(AdminInterface.getStandardServices())
53
    .build();
54

55
// Set service health status
56
healthManager.setStatus("my.service", ServingStatus.SERVING);
57

58
// Start server
59
server.start();
60
```
61

62
## Architecture
63

64
gRPC Services is organized around several key service areas:
65

66
- **Health Checking**: Server health status management with support for per-service health reporting
67
- **Server Reflection**: Protocol buffer service reflection for dynamic service discovery
68
- **Observability**: Channelz service for runtime introspection and debugging
69
- **Binary Logging**: Request/response logging for debugging and auditing
70
- **Metrics & Load Reporting**: ORCA metrics collection for load balancing and performance monitoring
71
- **Admin Services**: Standardized administrative service collection
72

73
Most APIs are marked as `@ExperimentalApi` indicating they are still evolving.
74

75
## Capabilities
76

77
### Health Checking Services
78

79
Server health status management for load balancer health checks and service monitoring. Provides both individual service status and overall server health reporting.
80

81
```java { .api }
82
public final class HealthStatusManager {
83
  public static final String SERVICE_NAME_ALL_SERVICES = "";
84
  
85
  public HealthStatusManager();
86
  public BindableService getHealthService();
87
  public void setStatus(String service, ServingStatus status);
88
  public void clearStatus(String service);
89
  public void enterTerminalState();
90
}
91
```
92

93
[Health Checking](./health-checking.md)
94

95
### Server Reflection Services
96

97
Protocol buffer service reflection enabling dynamic service discovery and debugging tools. Supports both v1alpha (deprecated) and v1 reflection protocols.
98

99
```java { .api }
100
public final class ProtoReflectionServiceV1 {
101
  public static BindableService newInstance();
102
  public StreamObserver<ServerReflectionRequest> serverReflectionInfo(
103
    StreamObserver<ServerReflectionResponse> responseObserver
104
  );
105
}
106
```
107

108
[Server Reflection](./server-reflection.md)
109

110
### Channelz Observability
111

112
Runtime introspection service providing detailed information about gRPC channels, servers, and connections for debugging and monitoring.
113

114
```java { .api }
115
public final class ChannelzService {
116
  public static ChannelzService newInstance(int maxPageSize);
117
  public void getTopChannels(GetTopChannelsRequest request, 
118
    StreamObserver<GetTopChannelsResponse> responseObserver);
119
  public void getServers(GetServersRequest request, 
120
    StreamObserver<GetServersResponse> responseObserver);
121
}
122
```
123

124
[Channelz Observability](./channelz.md)
125

126
### Binary Logging
127

128
Request and response logging system for debugging, auditing, and compliance. Supports configurable logging sinks and filtering.
129

130
```java { .api }
131
public final class BinaryLogs {
132
  public static BinaryLog createBinaryLog() throws IOException;
133
  public static BinaryLog createBinaryLog(BinaryLogSink sink, String configStr) 
134
    throws IOException;
135
}
136

137
public interface BinaryLogSink extends Closeable {
138
  void write(MessageLite message);
139
}
140
```
141

142
[Binary Logging](./binary-logging.md)
143

144
### Metrics and Load Reporting
145

146
ORCA metrics collection for load balancing and performance monitoring. Includes both per-call and out-of-band metrics reporting.
147

148
```java { .api }
149
public final class CallMetricRecorder {
150
  public static CallMetricRecorder getCurrent();
151
  public CallMetricRecorder recordUtilizationMetric(String name, double value);
152
  public CallMetricRecorder recordRequestCostMetric(String name, double value);
153
  public CallMetricRecorder recordCpuUtilizationMetric(double value);
154
}
155

156
public final class MetricRecorder {
157
  public static MetricRecorder newInstance();
158
  public void putUtilizationMetric(String key, double value);
159
  public void setCpuUtilizationMetric(double value);
160
}
161
```
162

163
[Metrics and Load Reporting](./metrics.md)
164

165
### Load Balancing Utilities
166

167
Client-side health checking utilities for load balancers and connection management.
168

169
```java { .api }
170
public final class HealthCheckingLoadBalancerUtil {
171
  public static LoadBalancer newHealthCheckingLoadBalancer(
172
    LoadBalancer.Factory factory, Helper helper);
173
}
174
```
175

176
[Load Balancing](./load-balancing.md)
177

178
### Admin Services
179

180
Collection of standard administrative services for gRPC servers including all built-in observability and management services.
181

182
```java { .api }
183
public final class AdminInterface {
184
  public static List<ServerServiceDefinition> getStandardServices();
185
}
186
```
187

188
[Admin Services](./admin-services.md)
189

190
## Types
191

192
```java { .api }
193
public enum ServingStatus {
194
  SERVING,
195
  NOT_SERVING,
196
  SERVICE_UNKNOWN
197
}
198

199
public class MetricReport {
200
  public double getCpuUtilization();
201
  public double getApplicationUtilization();
202
  public double getMemoryUtilization();
203
  public Map<String, Double> getRequestCostMetrics();
204
  public Map<String, Double> getUtilizationMetrics();
205
}
206
```