grpc-tools 
A suite of tools for gRPC debugging and development. Like Fiddler/Charles but for gRPC!
The main tool is grpc-dump which transparently intercepts network traffic and logs all gRPC and gRPC-Web requests with full metadata as a JSON stream. This stream is easily readable as it is or you can use tools like jq for more complex visualisation.
This repository currently includes:
grpc-dump: a small gRPC proxy that dumps RPC details to a file for debugging, and later analysis/replay.grpc-replay: takes the output fromgrpc-dumpand replays requests to the server.grpc-fixture: a proxy that takes the output fromgrpc-dumpand replays saved responses to client requests.grpc-proxy: a library for writing gRPC intercepting proxies.grpc-dumpandgrpc-fixtureare both built on top of this library.
These tools are in alpha so expect breaking changes between releases. See the changelog for full details.
Installation:
The recommended way to install these tools is via Homebrew using:
brew install bradleyjkemp/formulae/grpc-tools
Alternatively, binaries can be downloaded from the GitHub releases page.
Or you can build the tools from source using:
go install github.com/bradleyjkemp/grpc-tools/...
grpc-dump
grpc-dump lets you see all of the gRPC requests being made by applications on your machine without any code changes required to applications or servers.
Simply start grpc-dump and configure your system/application to use it as a HTTP(S) proxy. You’ll soon see requests logged in full as a JSON stream with service and method names.
Even if you don’t have the original .proto files, grpc-dump will attempt to deserialise messages heuristically to give a human readable form.
# start the proxy (leave out the --port flag to automatically pick on)
grpc-dump --port=12345
# in another terminal, run your application pointing it at the proxy
# Warning: if your application connects to a localhost/127.0.0.1 address then proxy settings
# are usually ignored. To fix this you can use a service like https://readme.localtest.me
http_proxy=http://localhost:12345 my-app
# all the requests made by the application will be logged to standard output in the grpc-dump window e.g.
# {"service": "echo", "method": "Hi", "messages": ["....."] }
# JSON will be logged to STDOUT and any info or warning messages will be logged to STDERR
Many applications expect to talk to a gRPC server over TLS. For this you need to use the --key and --cert flags to point grpc-dump to certificates valid for the domains your application connects to.
The recommended way to generate these files is via the excellent mkcert tool. grpc-dump will automatically use any mkcert generated certificates in the current directory.
# Configure your system to trust mkcert certificates
mkcert -install
# Generate certificates for domains you want to intercept connections to
mkcert mydomain.com *.mydomain.com
# Start grpc-dump using the key and certificate created by mkcert
# Or start grpc-dump from the same directory and it will
# detect them automatically
grpc-dump --key=mydomain.com-key.pem --cert=mydomain.com.pem
More details for using grpc-dump (including the specification for the JSON output) can be found here.
grpc-fixture
# save the (stdout) output of grpc-dump to a file
grpc-dump --port=12345 > my-app.dump
# in another, run your application pointing it at the proxy
http_proxy=http://localhost:12345 my-app
# now run grpc-fixture from the previously saved output
grpc-fixture --port=12345 --dump=my-app.dump
# when running the application again, all requests will
# be intercepted and answered with saved responses,
# no requests will be made to the real gRPC server.
http_proxy=http://localhost:12345 my-app
For applications that expect a TLS server, the same --key and --cert flags can be used as described above for grpc-dump.
More details for using grpc-fixture can be found here.