Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

gRPC Server Reflection Tutorial

gRPC Server Reflection provides information about publicly-accessible gRPC services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. It is used by gRPCurl, which can be used to introspect server protos and send/receive test RPCs.

Enable Server Reflection

gRPC-go Server Reflection is implemented in package reflection. To enable server reflection, you need to import this package and register reflection service on your gRPC server.

For example, to enable server reflection in example/helloworld, we need to make the following changes:

--- a/examples/helloworld/greeter_server/main.go
+++ b/examples/helloworld/greeter_server/main.go
@@ -40,6 +40,7 @@ import (
        pb ""
+       ""

 const (
@@ -61,6 +62,8 @@ func main() {
        s := grpc.NewServer()
        pb.RegisterGreeterService(s, &pb.GreeterService{SayHello: sayHello})
+       // Register reflection service on gRPC server.
+       reflection.Register(s)
        if err := s.Serve(lis); err != nil {
                log.Fatalf("failed to serve: %v", err)

An example server with reflection registered can be found at examples/features/reflection/server.


After enabling Server Reflection in a server application, you can use gRPCurl to check its services. gRPCurl is built with Go and has packages available. Instructions on how to install and use gRPCurl can be found at gRPCurl Installation.

Use gRPCurl to check services

First, start the helloworld server in grpc-go directory:

$ cd <grpc-go-directory>/examples
$ go run features/reflection/server/main.go


server listening at [::]:50051

After installing gRPCurl, open a new terminal and run the commands from the new terminal.

NOTE: gRPCurl expects a TLS-encrypted connection by default. For all of the commands below, use the -plaintext flag to use an unencrypted connection.

List services and methods

The list command lists services exposed at a given port:

  • List all the services exposed at a given port

    $ grpcurl -plaintext localhost:50051 list


  • List all the methods of a service

    The list command lists methods given the full service name (in the format of <package>.<service>).

    $ grpcurl -plaintext localhost:50051 list helloworld.Greeter



Describe services and methods

  • Describe all services

    The describe command inspects a service given its full name (in the format of <package>.<service>).

    $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter


    helloworld.Greeter is a service:
    service Greeter {
      rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );
  • Describe all methods of a service

    The describe command inspects a method given its full name (in the format of <package>.<service>.<method>).

    $ grpcurl -plaintext localhost:50051 describe helloworld.Greeter.SayHello


    helloworld.Greeter.SayHello is a method:
    rpc SayHello ( .helloworld.HelloRequest ) returns ( .helloworld.HelloReply );

Inspect message types

We can use the describe command to inspect request/response types given the full name of the type (in the format of <package>.<type>).

  • Get information about the request type

    $ grpcurl -plaintext localhost:50051 describe helloworld.HelloRequest


    helloworld.HelloRequest is a message:
    message HelloRequest {
      string name = 1;

Call a remote method

We can send RPCs to a server and get responses using the full method name (in the format of <package>.<service>.<method>). The -d <string> flag represents the request data and the -format text flag indicates that the request data is in text format.

  • Call a unary method

    $ grpcurl -plaintext -format text -d 'name: "gRPCurl"' \
      localhost:50051 helloworld.Greeter.SayHello


    message: "Hello gRPCurl"