| # 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](../../COMPILING.md). |
| |
| ### Build the example |
| |
| 1. Optional: Build the hello-world-debug example client. |
| See [the examples README](../README.md) |
| |
| 2. Build the debuggable server and client. From the |
| `grpc-java/examples/examples-debug` directory run: |
| |
| ```bash |
| $ ../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: |
| |
| ```bash |
| $ ./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 |
| |
| ```bash |
| $ ../build/install/examples/bin/hello-world-client |
| ``` |
| |
| debug enabled client |
| |
| ```bash |
| $ ./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](../README.md) |
| |
| 2. Run in this directory: |
| |
| ```bash |
| $ 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](https://github.com/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 |
| <br><br> |
| |
| #### Getting overall server info |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz servers |
| ``` |
| This will show you the server ids with their activity |
| ```text |
| Server ID Listen Addresses Calls(Started/Succeeded/Failed) Last Call Started |
| 2 [[::]:50051] 38/34/3 now |
| ``` |
| <br> |
| |
| #### Getting details for a service |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz server 2 |
| ``` |
| |
| The output will include more communication details and will show socket ids for |
| currently connected clients |
| |
| ```text |
| 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) |
| |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz socket 19 |
| ``` |
| |
| This will show a lot of gRPC internal information |
| |
| ```text |
| 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 |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz channels |
| ``` |
| Output |
| ```text |
| 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 |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz channel 3 |
| ``` |
| Output |
| ```text |
| 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 |
| ```bash |
| bin/grpcdebug/grpcdebug localhost:50051 channelz subchannel 10 |
| ``` |
| Output |
| ```text |
| 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 |
| ``` |
