grpc-java/examples/example-debug

gRPC Debug Example

The debug example uses a Hello World style server whose response includes its hostname. It demonstrates usage of the AdminInterface and the grpcdebug commandline tool.

The example requires grpc-java to already be built. You are strongly encouraged to check out a git release tag, since there will already be a build of grpc available. Otherwise, you must follow COMPILING.

Build the example

1. Optional: Build the hello-world-debug example client. See the examples README

2. Build the debuggable server and client. From the grpc-java/examples/examples-debug directory run:

$ ../gradlew installDist

This creates the scripts build/install/debug/bin/hostname-debuggable-server/bin/hostname-debuggable-server that runs the example.

To run the debug example, run:

$ ./build/install/debug/bin/hostname-debuggable-server/bin/hostname-debuggable-server

And in a different terminal window run the client.

Note: You can use the standard hello-world client with no debugging enabled and still see results on the server. However, if you want to get debug information about the client you need to run the hello-world-debuggable client.

Simple client

$ ../build/install/examples/bin/hello-world-client

debug enabled client

$ ./build/install/examples-debug/bin/hello-world-debuggable-client

Maven

If you prefer to use Maven:

1. Build the hello-world example client. See the examples README

2. Run in this directory:

$ mvn verify
$ # Run the server (from the examples-debug directory)
$ mvn exec:java -Dexec.mainClass=io.grpc.examples.debug.HostnameServer
$ # In another terminal run the client (from the examples directory)
$ cd ..
$ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldClient

Using grpcdebug

grpcdebug is a tool that has been created to access the metrics from the channelz and health services.

Installing the grpcdebug tool

The source code is located in a github project grpc-ecosystem/grpcdebug. You can either download [the latest built version] (https://github.com/grpc-ecosystem/grpcdebug/releases/latest) (recommended) or follow the README.md to build it yourself.

Running the grpcdebug tool

Usage

grpcdebug <target address> [flags] channelz <command> [argument]

Command	Argument	Description
channel	<channel id or URL>	Display channel states in a human readable way.
channels		Lists client channels for the target application.
server	<server ID>	Displays server state in a human readable way.
servers		Lists servers in a human readable way.
socket	<socket ID>	Displays socket states in a human readable way.
subchannel	<id>	Display subchannel states in human readable way.

Generally, you will start with either servers or channels and then work down to the details

Getting overall server info

bin/grpcdebug/grpcdebug localhost:50051 channelz servers

This will show you the server ids with their activity

Server ID   Listen Addresses   Calls(Started/Succeeded/Failed)   Last Call Started   
2           [[::]:50051]       38/34/3                           now                 

Getting details for a service

bin/grpcdebug/grpcdebug localhost:50051 channelz server 2

The output will include more communication details and will show socket ids for currently connected clients

Server Id:           2              
Listen Addresses:    [[::]:50051]   
Calls Started:       33             
Calls Succeeded:     29             
Calls Failed:        3              
Last Call Started:   now
---
Socket ID   Local->Remote              Streams(Started/Succeeded/Failed)   Messages(Sent/Received)   
19          [::1]:50051->[::1]:39834   4/3/0                               3/4

Displaying detailed info for a server side connection (socket)

bin/grpcdebug/grpcdebug localhost:50051 channelz socket 19

This will show a lot of gRPC internal information

Socket ID:                       19                         
Address:                         [::1]:50051->[::1]:50094   
Streams Started:                 1                          
Streams Succeeded:               0                          
Streams Failed:                  0                          
Messages Sent:                   0                          
Messages Received:               1                          
Keep Alives Sent:                0                          
Last Local Stream Created:                                  
Last Remote Stream Created:      now                        
Last Message Sent Created:                                  
Last Message Received Created:   now                        
Local Flow Control Window:       65535                      
Remote Flow Control Window:      1048569
---
Socket Options Name                                                                Value                                                                         
SO_LINGER                                                                          [type.googleapis.com/grpc.channelz.v1.SocketOptionLinger]:{}                  
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_CORK            false                                                                         
WRITE_BUFFER_HIGH_WATER_MARK                                                       65536                                                                         
WRITE_BUFFER_LOW_WATER_MARK                                                        32768                                                                         
IP_TOS                                                                             0                                                                             
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_KEEPCNT         9                                                                             
SINGLE_EVENTEXECUTOR_PER_GROUP                                                     true                                                                          
SO_SNDBUF                                                                          2626560                                                                       
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_NOTSENT_LOWAT   0                                                                             
WRITE_BUFFER_WATER_MARK                                                            WriteBufferWaterMark(low: 32768, high: 65536)                                 
TCP_NODELAY                                                                        true                                                                          
SO_RCVBUF                                                                          131072                                                                        
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#SO_BUSY_POLL        0                                                                             
IP_TRANSPARENT                                                                     false                                                                         
SO_KEEPALIVE                                                                       true                                                                          
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_QUICKACK        false                                                                         
ALLOCATOR                                                                          PooledByteBufAllocator(directByDefault: true)                                 
TCP_FASTOPEN_CONNECT                                                               false                                                                         
MESSAGE_SIZE_ESTIMATOR                                                             io.grpc.netty.shaded.io.netty.channel.DefaultMessageSizeEstimator@48d475b6    
WRITE_SPIN_COUNT                                                                   16                                                                            
SO_REUSEADDR                                                                       true                                                                          
CONNECT_TIMEOUT_MILLIS                                                             30000                                                                         
ALLOW_HALF_CLOSURE                                                                 false                                                                         
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#EPOLL_MODE          EDGE_TRIGGERED                                                                
MAX_MESSAGES_PER_READ                                                              16                                                                            
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_KEEPIDLE        7200                                                                          
AUTO_CLOSE                                                                         true                                                                          
io.grpc.netty.shaded.io.netty.channel.epoll.EpollChannelOption#TCP_KEEPINTVL       75                                                                            
MAX_MESSAGES_PER_WRITE                                                             2147483647                                                                    
AUTO_READ                                                                          true                                                                          
TCP_MD5SIG                                                                         null                                                                          
RCVBUF_ALLOCATOR                                                                   io.grpc.netty.shaded.io.netty.channel.AdaptiveRecvByteBufAllocator@360691a0   

Displaying the list of gRPC client channels

Command

bin/grpcdebug/grpcdebug localhost:50051 channelz channels

Output

Channel ID   Target            State     Calls(Started/Succeeded/Failed)   Created Time   
1            localhost:50051   READY     34/34/0                                          
3            localhost:50051   READY     16/16/0

Note: If you have a simple server that doesn't use gRPC clients to contact other servers, then this table will be empty.

Displaying details of a gRPC client channel

Command

bin/grpcdebug/grpcdebug localhost:50051 channelz channel 3

Output

Channel ID:        3                 
Target:            localhost:50051   
State:             READY             
Calls Started:     16                
Calls Succeeded:   16                
Calls Failed:      0                 
Created Time:                        
---
Subchannel ID   Target                                               State     Calls(Started/Succeeded/Failed)   CreatedTime   
10              [[[localhost/127.0.0.1:50051]/{}], [[localhost/0:0   READY     16/16/0                                                                                

Displaying details of a gRPC client subchannel

Command

bin/grpcdebug/grpcdebug localhost:50051 channelz subchannel 10

Output

Subchannel ID:     10                                                                           
Target:            [[[localhost/127.0.0.1:50051]/{}], [[localhost/0:0:0:0:0:0:0:1:50051]/{}]]   
State:             READY                                                                        
Calls Started:     16                                                                           
Calls Succeeded:   16                                                                           
Calls Failed:      0                                                                            
Created Time:                                                                                   
---
Socket ID   Local->Remote                      Streams(Started/Succeeded/Failed)   Messages(Sent/Received)   
11          127.0.0.1:48536->127.0.0.1:50051   16/16/0                             12/12