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.
The recommended way to install these tools is via Homebrew using:
brew install bradleyjkemp/formulae/grpc-toolsAlternatively, 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 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 STDERRMany 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.pemMore details for using grpc-dump (including the specification for the JSON output) can be found here.
# 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-appFor 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.