Repository files navigation

A suite of tools for gRPC debugging and development. LikeFiddler/Charles but for gRPC!

The main tool isgrpc-dump which transparently intercepts network traffic and logs all gRPC and gRPC-Web requests with full metadata as a JSONstream. This stream is easily readable as it is or you can use tools likejq 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-dump and replays requests to the server.
• grpc-fixture: a proxy that takes the output fromgrpc-dump and replays saved responses to client requests.
• grpc-proxy: a library for writing gRPC intercepting proxies.grpc-dump andgrpc-fixture are both built on top of this library.

These tools are in alpha so expect breaking changes between releases. See thechangelog for full details.

The recommended way to install these tools is viaHomebrew using:

brew install bradleyjkemp/formulae/grpc-tools

Alternatively, binaries can be downloaded from the GitHubreleases 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 startgrpc-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.mehttp_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 pointgrpc-dump to certificates valid for the domains your application connects to.

The recommended way to generate these files is via the excellentmkcert tool.grpc-dump will automatically use anymkcert generated certificates in the current directory.

# Configure your system to trust mkcert certificatesmkcert -install# Generate certificates for domains you want to intercept connections tomkcert 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 automaticallygrpc-dump --key=mydomain.com-key.pem --cert=mydomain.com.pem

More details for usinggrpc-dump (including the specification for the JSON output) can be foundhere.

# save the (stdout) output of grpc-dump to a filegrpc-dump --port=12345> my-app.dump# in another, run your application pointing it at the proxyhttp_proxy=http://localhost:12345 my-app# now run grpc-fixture from the previously saved outputgrpc-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 forgrpc-dump.

More details for usinggrpc-fixture can be foundhere.