examples: add example to show how to use the health service #3381

mjpitz · 2020-02-15T01:58:36Z

Resolves #2770

linux-foundation-easycla · 2020-02-15T01:58:38Z

The committers are authorized under a signed CLA.

✅ Mya Pitzeruse (b7bd287, 28aa0ac, ddac5c6)

dfawley

Sorry for the long radio silence. This looks great, thank you! I have a few minor wording changes suggested. In terms of the example, it would be nice to demonstrate the client auto-checking in action, but at the same time I recognize that it's hard to set up, and even then it might be hard for a person to fully grasp what it's doing. An idea I had:

Server binary starts two servers on two ports exposing the same service. The servers respond with a unique message so you can see which is being used.
Client is created with a manual resolver that injects both server addresses (typically DNS would do this instead), uses a service config that sets a round_robin LB policy with health checks enabled, and then performs RPCs.
Client then sends a simple RPC and shows the two servers being alternated. Then one server disables itself and we observe only one server being used on the client.

If that sounds like something you're interested in doing, or if you have a better idea for showing off the feature fully, then it can be done in another PR. If not, I'll add it into the issue and we can leave it open. Either way we can just do the few minor changes in this PR and merge it.

Thanks!

dfawley · 2020-03-20T20:53:14Z

examples/features/health/README.md

@@ -0,0 +1,59 @@
+# Health
+
+gRPC provides a health library to communicate a systems health to their clients.


Suggested change

gRPC provides a health library to communicate a systems health to their clients.

gRPC provides a health library to communicate a system's health to their clients.

dfawley · 2020-03-20T20:54:00Z

examples/features/health/README.md

+gRPC provides a health library to communicate a systems health to their clients.
+It works by providing a service definition via the [health/v1](https://github.com/grpc/grpc-proto/blob/master/grpc/health/v1/health.proto) api.
+
+By using the health library, clients can gracefully fail out servers as they encounter issues. 


Suggested change

By using the health library, clients can gracefully fail out servers as they encounter issues.

By using the health library, clients can gracefully avoid using servers as they encounter issues.

dfawley · 2020-03-20T20:55:38Z

examples/features/health/README.md

+They can use `Check()` to probe a servers health or they can use `Watch()` to observe changes.
+
+In most cases, clients do not need to directly check backend servers.
+Instead, they can do this transparently when a `healthCheckConfig` is specified.


Suggested change

Instead, they can do this transparently when a `healthCheckConfig` is specified.

Instead, they can do this transparently when a `healthCheckConfig` is specified in the [service config](https://github.com/grpc/proposal/blob/master/A17-client-side-health-checking.md#service-config-changes).

mjpitz · 2020-03-21T02:20:29Z

I'll make the minor changes, but can also work on updating the example to show both direct and transparent use.

mjpitz · 2020-03-21T02:59:38Z

@dfawley updated based on your feedback and included a transparent example

dfawley

Very nice, thank you for making the changes! A few comments below.

Also, please check the travis errors (for now it's missing copyright notices on top of client & server main.gos making it fail.

dfawley · 2020-03-23T15:31:41Z

examples/features/health/server/main.go

 	"google.golang.org/grpc/health"
 	healthpb "google.golang.org/grpc/health/grpc_health_v1"
 )

 var (
+	defaultSleep = time.Second * 5


Nit: please remove this variable only used once.

dfawley · 2020-03-23T15:33:19Z

examples/features/health/client/main.go

 		time.Sleep(time.Second)
 	}
 }

-func main() {
-	flag.Parse()
+// Following is an example name resolver implementation. Read the name


Sorry for not being clearer. This implementation is not necessary; please use the manual resolver instead to inject the server addresses: https://godoc.org/google.golang.org/grpc/resolver/manual

Let me know if its usage isn't clear and I can help (we also use this in many tests if you would like to see examples).

I did notice the manual resolver and tried poking around it for a bit. I will take another look at it and how to use it. I was actually thinking about writing a quick static resolver that would accept a scheme like static:///addr1,addr2,...

@mjpitz,

To use the manual resolver, I think you can do something like:

r, cleanup := manual.GenerateAndRegisterManualResolver() defer cleanup() r.InitialState(resolver.State{Addresses: []resolver.Address{{Addr: ... }, ...}) cc, err := grpc.Dial(r.Scheme()+":///unused")

Let me know if you have any problems. Thanks!

Oh, no I figured that. It was just something I thought about writing before.

dfawley · 2020-03-23T15:39:52Z

examples/features/health/client/main.go

+	r, err := c.UnaryEcho(ctx, &pb.EchoRequest{})
+	if err == nil {
+		fmt.Println("UnaryEcho: ", r.GetMessage())
 	}


It would be nice to print something in case there is an error, for debugging purposes. How about unconditionally printing both r.GetMessage() and err?

And, actually, if you use different periods for the two servers (5s and 10s as in the example), then we do expect to see timeouts when they are both in the unhealthy phase for more than 1s.

mjpitz · 2020-04-03T19:37:59Z

@dfawley updated based on your feedback. I'll keep an eye on the Travis job. Let me know if there is anything further.

dfawley

Thanks for the changes. There's just a few small things left.

dfawley · 2020-04-03T19:41:24Z

examples/features/health/client/main.go

@@ -1,3 +1,21 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.


Please update to 2020

dfawley · 2020-04-03T19:42:57Z

examples/features/health/client/main.go

 func callUnaryEcho(c pb.EchoClient) {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
 	r, err := c.UnaryEcho(ctx, &pb.EchoRequest{})
-	if err == nil {
+	if err != nil {
+		fmt.Println(fmt.Sprintf("UnaryEcho: _, %v", err))


This can be simplified a bit:

fmt.Printf("UnaryEcho: _, %v\n", err)
or
fmt.Println("UnaryEcho: _, ", err)

dfawley · 2020-04-03T19:44:22Z

examples/features/health/server/main.go

@@ -1,3 +1,21 @@
+/*
+ *
+ * Copyright 2018 gRPC authors.


Please update date.

mjpitz · 2020-04-03T19:48:51Z

@dfawley done!

dfawley · 2020-04-03T22:36:08Z

+gofmt -s -d -l .
+tee /dev/stderr
+not read
+read
examples/features/health/client/main.go

I think what all this verbosity means is that client/main.go needs to be run through gofmt. Please check this out, thanks!

menghanl · 2020-04-03T22:45:56Z

Run gofmt -s -d -l -w . (adding -w), the code should be updated.

mjpitz · 2020-04-03T23:10:01Z

Ran gofmt, looks like it's all green. Thanks!

dfawley

Nice, thank you for the contribution!

mjpitz added 3 commits February 12, 2020 19:40

gh-2770: stubbed out client and server demonstration

b7bd287

gh-2770: added explanation to readme

28aa0ac

gh-2770: added preface about the health api

ddac5c6

menghanl assigned dfawley Feb 20, 2020

menghanl requested a review from dfawley February 20, 2020 21:13

menghanl added the Type: Documentation Documentation or examples label Feb 20, 2020

menghanl added this to the 1.28 Release milestone Feb 20, 2020

menghanl mentioned this pull request Feb 20, 2020

how to use health check service #3382

Closed

dfawley modified the milestones: 1.28 Release, 1.29 Release Mar 5, 2020

dfawley reviewed Mar 20, 2020

View reviewed changes

dfawley assigned mjpitz and unassigned dfawley Mar 20, 2020

mjpitz added 2 commits March 20, 2020 21:24

gh-2770: updated readme with feedback from PR.

20eddff

gh-2770: updated code to demonstrate the transparent use of healthchecks

5b6d518

dfawley reviewed Mar 23, 2020

View reviewed changes

dfawley added the Status: Requires Reporter Clarification label Apr 2, 2020

gh-2770: added header and updated client to use manual resolver

fbae36b

dfawley reviewed Apr 3, 2020

View reviewed changes

gh-2770: fixup copyright date and simplified print logic

d73db23

dfawley unassigned mjpitz Apr 3, 2020

dfawley removed the Status: Requires Reporter Clarification label Apr 3, 2020

dfawley self-assigned this Apr 3, 2020

gh-2770: ran gofmt

33eae55

dfawley approved these changes Apr 8, 2020

View reviewed changes

dfawley changed the title ~~gh-2770: add documentation around use of the health API~~ examples: add example to show how to use the health service Apr 8, 2020

dfawley merged commit 3038e58 into grpc:master Apr 8, 2020

github-actions bot locked as resolved and limited conversation to collaborators May 25, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

examples: add example to show how to use the health service #3381

examples: add example to show how to use the health service #3381

mjpitz commented Feb 15, 2020

linux-foundation-easycla bot commented Feb 15, 2020 •

edited

dfawley left a comment

dfawley Mar 20, 2020

dfawley Mar 20, 2020

dfawley Mar 20, 2020

mjpitz commented Mar 21, 2020

mjpitz commented Mar 21, 2020 •

edited

dfawley left a comment

dfawley Mar 23, 2020

dfawley Mar 23, 2020

mjpitz Mar 23, 2020

dfawley Apr 2, 2020

mjpitz Apr 3, 2020

dfawley Mar 23, 2020

mjpitz commented Apr 3, 2020

dfawley left a comment

dfawley Apr 3, 2020

dfawley Apr 3, 2020

dfawley Apr 3, 2020

mjpitz commented Apr 3, 2020

dfawley commented Apr 3, 2020

menghanl commented Apr 3, 2020

mjpitz commented Apr 3, 2020

dfawley left a comment

		@@ -0,0 +1,59 @@
		# Health

		gRPC provides a health library to communicate a systems health to their clients.

	By using the health library, clients can gracefully fail out servers as they encounter issues.
	By using the health library, clients can gracefully avoid using servers as they encounter issues.

	Instead, they can do this transparently when a `healthCheckConfig` is specified.
	Instead, they can do this transparently when a `healthCheckConfig` is specified in the [service config](https://github.com/grpc/proposal/blob/master/A17-client-side-health-checking.md#service-config-changes).

examples: add example to show how to use the health service #3381

examples: add example to show how to use the health service #3381

Conversation

mjpitz commented Feb 15, 2020

linux-foundation-easycla bot commented Feb 15, 2020 • edited

dfawley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjpitz commented Mar 21, 2020

mjpitz commented Mar 21, 2020 • edited

dfawley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjpitz commented Apr 3, 2020

dfawley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjpitz commented Apr 3, 2020

dfawley commented Apr 3, 2020

menghanl commented Apr 3, 2020

mjpitz commented Apr 3, 2020

dfawley left a comment

Choose a reason for hiding this comment

linux-foundation-easycla bot commented Feb 15, 2020 •

edited

mjpitz commented Mar 21, 2020 •

edited