From 0a494caf82c2273eaf77091d381993478068f0e3 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Wed, 1 Apr 2026 13:59:22 -0700 Subject: [PATCH 1/3] examples: Clean up Health, and document need for grpc-services For something like this, putting all the config together in service config is what we would want to encourage. Remove unused/needless variables. Emphasize health checking more than round-robin. Add missing synchronization on server-side. --- examples/build.gradle | 2 + .../healthservice/HealthServiceClient.java | 65 +++++++++---------- .../healthservice/HealthServiceServer.java | 4 +- .../io/grpc/examples/healthservice/README.md | 9 ++- 4 files changed, 42 insertions(+), 38 deletions(-) diff --git a/examples/build.gradle b/examples/build.gradle index 62e50d38861..688121c677e 100644 --- a/examples/build.gradle +++ b/examples/build.gradle @@ -27,6 +27,8 @@ def protocVersion = protobufVersion dependencies { implementation "io.grpc:grpc-protobuf:${grpcVersion}" + // Even though client-side won't call grpc-services directly, it needs the + // dependency to enable the health-aware round_robin implementation implementation "io.grpc:grpc-services:${grpcVersion}" implementation "io.grpc:grpc-stub:${grpcVersion}" diff --git a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java index 471084feab6..f045e1266b7 100644 --- a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java +++ b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java @@ -32,6 +32,7 @@ import io.grpc.health.v1.HealthCheckResponse.ServingStatus; import io.grpc.health.v1.HealthGrpc; import java.util.Arrays; +import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.concurrent.TimeUnit; @@ -45,25 +46,17 @@ public class HealthServiceClient { private static final Logger logger = Logger.getLogger(HealthServiceClient.class.getName()); private final GreeterGrpc.GreeterBlockingStub greeterBlockingStub; - private final HealthGrpc.HealthStub healthStub; private final HealthGrpc.HealthBlockingStub healthBlockingStub; - private final HealthCheckRequest healthRequest; - /** Construct client for accessing HelloWorld server using the existing channel. */ public HealthServiceClient(Channel channel) { greeterBlockingStub = GreeterGrpc.newBlockingStub(channel); - healthStub = HealthGrpc.newStub(channel); healthBlockingStub = HealthGrpc.newBlockingStub(channel); - healthRequest = HealthCheckRequest.getDefaultInstance(); - LoadBalancerProvider roundRobin = LoadBalancerRegistry.getDefaultRegistry() - .getProvider("round_robin"); - } private ServingStatus checkHealth(String prefix) { HealthCheckResponse response = - healthBlockingStub.check(healthRequest); + healthBlockingStub.check(HealthCheckRequest.getDefaultInstance()); logger.info(prefix + ", current health is: " + response.getStatus()); return response.getStatus(); } @@ -86,34 +79,35 @@ public void greet(String name) { } - private static void runTest(String target, String[] users, boolean useRoundRobin) + private static void runTest(String target, String[] users, boolean enableHealthChecking) throws InterruptedException { - ManagedChannelBuilder builder = - Grpc.newChannelBuilder(target, InsecureChannelCredentials.create()); - - // Round Robin, when a healthCheckConfig is present in the default service configuration, runs - // a watch on the health service and when picking an endpoint will - // consider a transport to a server whose service is not in SERVING state to be unavailable. - // Since we only have a single server we are connecting to, then the load balancer will - // return an error without sending the RPC. - if (useRoundRobin) { - builder = builder - .defaultLoadBalancingPolicy("round_robin") - .defaultServiceConfig(generateHealthConfig("")); + // Enable the round_robin load balancer, with or without health checking. + Map serviceConfig; + if (enableHealthChecking) { + serviceConfig = generateServiceConfig(""); + } else { + serviceConfig = generateServiceConfig(null); } + ManagedChannel channel = + Grpc.newChannelBuilder(target, InsecureChannelCredentials.create()) + .defaultServiceConfig(serviceConfig) + .build(); - ManagedChannel channel = builder.build(); + // Round Robin, when a healthCheckConfig is present in the service configuration, runs a watch + // on the health service and when picking an endpoint will consider a transport to a server + // whose service is not in SERVING state to be unavailable. Since we only have a single server + // we are connecting to, then the load balancer will return an error without sending the RPC. - System.out.println("\nDoing test with" + (useRoundRobin ? "" : "out") - + " the Round Robin load balancer\n"); + System.out.println("\nDoing test with" + (enableHealthChecking ? "" : "out") + + " health checking\n"); try { HealthServiceClient client = new HealthServiceClient(channel); - if (!useRoundRobin) { + if (!enableHealthChecking) { client.checkHealth("Before call"); } client.greet(users[0]); - if (!useRoundRobin) { + if (!enableHealthChecking) { client.checkHealth("After user " + users[0]); } @@ -122,7 +116,7 @@ private static void runTest(String target, String[] users, boolean useRoundRobin Thread.sleep(100); // Since the health update is asynchronous give it time to propagate } - if (!useRoundRobin) { + if (!enableHealthChecking) { client.checkHealth("After all users"); Thread.sleep(10000); client.checkHealth("After 10 second wait"); @@ -137,12 +131,17 @@ private static void runTest(String target, String[] users, boolean useRoundRobin channel.shutdownNow().awaitTermination(5, TimeUnit.SECONDS); } } - private static Map generateHealthConfig(String serviceName) { + private static Map generateServiceConfig(String healthServiceName) { Map config = new HashMap<>(); - Map serviceMap = new HashMap<>(); - - config.put("healthCheckConfig", serviceMap); - serviceMap.put("serviceName", serviceName); + if (healthServiceName != null) { + config.put("healthCheckConfig", Collections.singletonMap("serviceName", healthServiceName)); + } + // There is more than one round_robin implementation. If the client doesn't depend on + // io.grpc:grpc-services, then the round_robin implementation does not support health watching + // (to avoid a Protobuf dependency). When the client depends on grpc-services the + // health-supporting round_robin implementation is used instead. + config.put("loadBalancingConfig", Arrays.asList( + Collections.singletonMap("round_robin", Collections.emptyMap()))); return config; } diff --git a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceServer.java b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceServer.java index f6547c11103..2170c9d3e08 100644 --- a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceServer.java +++ b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceServer.java @@ -94,7 +94,7 @@ public static void main(String[] args) throws IOException, InterruptedException } private class GreeterImpl extends GreeterGrpc.GreeterImplBase { - boolean isServing = true; + private volatile boolean isServing = true; @Override public void sayHello(HelloRequest req, StreamObserver responseObserver) { @@ -134,7 +134,7 @@ public void run() { } private boolean isNameLongEnough(HelloRequest req) { - return isServing && req.getName().length() >= 5; + return req.getName().length() >= 5; } } } diff --git a/examples/src/main/java/io/grpc/examples/healthservice/README.md b/examples/src/main/java/io/grpc/examples/healthservice/README.md index 181bd70977f..9b17f96a624 100644 --- a/examples/src/main/java/io/grpc/examples/healthservice/README.md +++ b/examples/src/main/java/io/grpc/examples/healthservice/README.md @@ -1,10 +1,13 @@ gRPC Health Service Example ===================== -The Health Service example provides a HelloWorld gRPC server that doesn't like short names along with a -health service. It also provides a client application which makes HelloWorld -calls and checks the health status. +The Health Service example provides a HelloWorld gRPC server that doesn't like +short names along with a health service. It also provides a client application +which makes HelloWorld calls and checks the health status. The client application also shows how the round robin load balancer can utilize the health status to avoid making calls to a service that is not actively serving. + +Note that clients must depend on `io.grpc:grpc-services` for the health-aware +round_robin implementation to be used. From 6caad60bede20abd82fc0cf74e1ca2553daeb461 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Wed, 8 Apr 2026 10:55:13 -0700 Subject: [PATCH 2/3] Apply suggestion from @dfawley Co-authored-by: Doug Fawley --- .../grpc/examples/healthservice/HealthServiceClient.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java index f045e1266b7..b45f257b380 100644 --- a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java +++ b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java @@ -82,15 +82,15 @@ public void greet(String name) { private static void runTest(String target, String[] users, boolean enableHealthChecking) throws InterruptedException { // Enable the round_robin load balancer, with or without health checking. - Map serviceConfig; + String healthServiceName; if (enableHealthChecking) { - serviceConfig = generateServiceConfig(""); + healthServiceName = ""; // represents the "overall health status" } else { - serviceConfig = generateServiceConfig(null); + healthServiceName = null; // disables health checking } ManagedChannel channel = Grpc.newChannelBuilder(target, InsecureChannelCredentials.create()) - .defaultServiceConfig(serviceConfig) + .defaultServiceConfig(generateServiceConfig(healthServiceName)) .build(); // Round Robin, when a healthCheckConfig is present in the service configuration, runs a watch From 773bcb6c4146864991884a63fbca8976d061f882 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Wed, 8 Apr 2026 10:57:42 -0700 Subject: [PATCH 3/3] Fixup/improve comments --- .../io/grpc/examples/healthservice/HealthServiceClient.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java index b45f257b380..a7963630965 100644 --- a/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java +++ b/examples/src/main/java/io/grpc/examples/healthservice/HealthServiceClient.java @@ -81,15 +81,15 @@ public void greet(String name) { private static void runTest(String target, String[] users, boolean enableHealthChecking) throws InterruptedException { - // Enable the round_robin load balancer, with or without health checking. String healthServiceName; if (enableHealthChecking) { - healthServiceName = ""; // represents the "overall health status" + healthServiceName = ""; // requests the backend's "overall health status" } else { - healthServiceName = null; // disables health checking + healthServiceName = null; // disables health checking in generateServiceConfig() } ManagedChannel channel = Grpc.newChannelBuilder(target, InsecureChannelCredentials.create()) + // Enable the round_robin load balancer, with or without health checking .defaultServiceConfig(generateServiceConfig(healthServiceName)) .build();