1# gRPC Server Reflection Tutorial
2
3gRPC Server Reflection provides information about publicly-accessible gRPC
4services on a server, and assists clients at runtime to construct RPC requests
5and responses without precompiled service information. It is used by
6[gRPCurl](https://github.com/fullstorydev/grpcurl), which can be used to
7introspect server protos and send/receive test RPCs.
8
9## Enable Server Reflection
10
11gRPC-go Server Reflection is implemented in package
12[reflection](https://github.com/grpc/grpc-go/tree/master/reflection). To enable
13server reflection, you need to import this package and register reflection
14service on your gRPC server.
15
16For example, to enable server reflection in `example/helloworld`, we need to
17make the following changes:
18
19```diff
20--- a/examples/helloworld/greeter_server/main.go
21+++ b/examples/helloworld/greeter_server/main.go
22@@ -40,6 +40,7 @@ import (
23 "google.golang.org/grpc"
24 pb "google.golang.org/grpc/examples/helloworld/helloworld"
25+ "google.golang.org/grpc/reflection"
26 )
27
28 const (
29@@ -61,6 +62,8 @@ func main() {
30 }
31 s := grpc.NewServer()
32 pb.RegisterGreeterService(s, &pb.GreeterService{SayHello: sayHello})
33+ // Register reflection service on gRPC server.
34+ reflection.Register(s)
35 if err := s.Serve(lis); err != nil {
36 log.Fatalf("failed to serve: %v", err)
37 }
38```
39
40An example server with reflection registered can be found at
41`examples/features/reflection/server`.
42
43## gRPCurl
44
45After enabling Server Reflection in a server application, you can use gRPCurl
46to check its services. gRPCurl is built with Go and has packages available.
47Instructions on how to install and use gRPCurl can be found at
48[gRPCurl Installation](https://github.com/fullstorydev/grpcurl#installation).
49
50## Use gRPCurl to check services
51
52First, start the helloworld server in grpc-go directory:
53
54```sh
55$ cd <grpc-go-directory>/examples
56$ go run features/reflection/server/main.go
57```
58
59output:
60```sh
61server listening at [::]:50051
62```
63
64After installing gRPCurl, open a new terminal and run the commands from the new
65terminal.
66
67**NOTE:** gRPCurl expects a TLS-encrypted connection by default. For all of
68the commands below, use the `-plaintext` flag to use an unencrypted connection.
69
70### List services and methods
71
72The `list` command lists services exposed at a given port:
73
74- List all the services exposed at a given port
75
76 ```sh
77 $ grpcurl -plaintext localhost:50051 list
78 ```
79
80 output:
81 ```sh
82 grpc.examples.echo.Echo
83 grpc.reflection.v1alpha.ServerReflection
84 helloworld.Greeter
85 ```
86
87- List all the methods of a service
88
89 The `list` command lists methods given the full service name (in the format of
90 \<package\>.\<service\>).
91
92 ```sh
93 $ grpcurl -plaintext localhost:50051 list helloworld.Greeter
94 ```
95
96 output:
97 ```sh
98 helloworld.Greeter.SayHello
99 ```
100
101### Describe services and methods
102
103- Describe all services
104
105 The `describe` command inspects a service given its full name (in the format
106 of \<package\>.\<service\>).
107
108 ```sh
109 $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter
110 ```
111
112 output:
113 ```sh
114 helloworld.Greeter is a service:
115 service Greeter {
116 rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
117 }
118 ```
119
120- Describe all methods of a service
121
122 The `describe` command inspects a method given its full name (in the format of
123 \<package\>.\<service\>.\<method\>).
124
125 ```sh
126 $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello
127 ```
128
129 output:
130 ```sh
131 helloworld.Greeter.SayHello is a method:
132 rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
133 ```
134
135### Inspect message types
136
137We can use the `describe` command to inspect request/response types given the
138full name of the type (in the format of \<package\>.\<type\>).
139
140- Get information about the request type
141
142 ```sh
143 $ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest
144 ```
145
146 output:
147 ```sh
148 helloworld.HelloRequest is a message:
149 message HelloRequest {
150 string name = 1;
151 }
152 ```
153
154### Call a remote method
155
156We can send RPCs to a server and get responses using the full method name (in
157the format of \<package\>.\<service\>.\<method\>). The `-d <string>` flag
158represents the request data and the `-format text` flag indicates that the
159request data is in text format.
160
161- Call a unary method
162
163 ```sh
164 $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
165 localhost:50051 helloworld.Greeter.SayHello
166 ```
167
168 output:
169 ```sh
170 message: "Hello gRPCurl"
171 ```
View as plain text