vendor/google.golang.org/grpc/Documentation/server-reflection-tutorial.md

   1 # gRPC Server Reflection Tutorial
   2
   3 gRPC Server Reflection provides information about publicly-accessible gRPC
   4 services on a server, and assists clients at runtime to construct RPC
   5 requests and responses without precompiled service information. It is used by
   6 gRPC CLI, which can be used to introspect server protos and send/receive test
   7 RPCs.
   8
   9 ## Enable Server Reflection
  10
  11 gRPC-go Server Reflection is implemented in package [reflection](https://github.com/grpc/grpc-go/tree/master/reflection). To enable server reflection, you need to import this package and register reflection service on your gRPC server.
  12
  13 For example, to enable server reflection in `example/helloworld`, we need to make the following changes:
  14
  15 ```diff
  16 --- a/examples/helloworld/greeter_server/main.go
  17 +++ b/examples/helloworld/greeter_server/main.go
  18 @@ -40,6 +40,7 @@ import (
  19         "golang.org/x/net/context"
  20         "google.golang.org/grpc"
  21         pb "google.golang.org/grpc/examples/helloworld/helloworld"
  22 +       "google.golang.org/grpc/reflection"
  23  )
  24
  25  const (
  26 @@ -61,6 +62,8 @@ func main() {
  27         }
  28         s := grpc.NewServer()
  29         pb.RegisterGreeterServer(s, &server{})
  30 +       // Register reflection service on gRPC server.
  31 +       reflection.Register(s)
  32         if err := s.Serve(lis); err != nil {
  33                 log.Fatalf("failed to serve: %v", err)
  34         }
  35 ```
  36
  37 We have made this change in `example/helloworld`, and we will use it as an example to show the use of gRPC server reflection and gRPC CLI in this tutorial.
  38
  39 ## gRPC CLI
  40
  41 After enabling Server Reflection in a server application, you can use gRPC CLI to check its services.
  42 gRPC CLI is only available in c++. Instructions on how to use gRPC CLI can be found at [command_line_tool.md](https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md).
  43
  44 To build gRPC CLI:
  45
  46 ```sh
  47 git clone https://github.com/grpc/grpc
  48 cd grpc
  49 make grpc_cli
  50 cd bins/opt # grpc_cli is in directory bins/opt/
  51 ```
  52
  53 ## Use gRPC CLI to check services
  54
  55 First, start the helloworld server in grpc-go directory:
  56
  57 ```sh
  58 $ cd <grpc-go-directory>
  59 $ go run examples/helloworld/greeter_server/main.go
  60 ```
  61
  62 Open a new terminal and make sure you are in the directory where grpc_cli lives:
  63
  64 ```sh
  65 $ cd <grpc-cpp-dirctory>/bins/opt
  66 ```
  67
  68 ### List services
  69
  70 `grpc_cli ls` command lists services and methods exposed at a given port:
  71
  72 - List all the services exposed at a given port
  73
  74   ```sh
  75   $ ./grpc_cli ls localhost:50051
  76   ```
  77
  78   output:
  79   ```sh
  80   helloworld.Greeter
  81   grpc.reflection.v1alpha.ServerReflection
  82   ```
  83
  84 - List one service with details
  85
  86   `grpc_cli ls` command inspects a service given its full name (in the format of
  87   \<package\>.\<service\>). It can print information with a long listing format
  88   when `-l` flag is set. This flag can be used to get more details about a
  89   service.
  90
  91   ```sh
  92   $ ./grpc_cli ls localhost:50051 helloworld.Greeter -l
  93   ```
  94
  95   output:
  96   ```sh
  97   filename: helloworld.proto
  98   package: helloworld;
  99   service Greeter {
 100     rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
 101   }
 102
 103   ```
 104
 105 ### List methods
 106
 107 - List one method with details
 108
 109   `grpc_cli ls` command also inspects a method given its full name (in the
 110   format of \<package\>.\<service\>.\<method\>).
 111
 112   ```sh
 113   $ ./grpc_cli ls localhost:50051 helloworld.Greeter.SayHello -l
 114   ```
 115
 116   output:
 117   ```sh
 118     rpc SayHello(helloworld.HelloRequest) returns (helloworld.HelloReply) {}
 119   ```
 120
 121 ### Inspect message types
 122
 123 We can use`grpc_cli type` command to inspect request/response types given the
 124 full name of the type (in the format of \<package\>.\<type\>).
 125
 126 - Get information about the request type
 127
 128   ```sh
 129   $ ./grpc_cli type localhost:50051 helloworld.HelloRequest
 130   ```
 131
 132   output:
 133   ```sh
 134   message HelloRequest {
 135     optional string name = 1[json_name = "name"];
 136   }
 137   ```
 138
 139 ### Call a remote method
 140
 141 We can send RPCs to a server and get responses using `grpc_cli call` command.
 142
 143 - Call a unary method
 144
 145   ```sh
 146   $ ./grpc_cli call localhost:50051 SayHello "name: 'gRPC CLI'"
 147   ```
 148
 149   output:
 150   ```sh
 151   message: "Hello gRPC CLI"
 152   ```