kevwan/tproxy: a TCP relay for watching gRPC, MySQL and Redis connections

The problem tproxy solves: connection behaviour you cannot see from logs

Application logs tell you a query ran. They rarely tell you that the client opened four connections to MySQL in the same second, kept one idle for eleven minutes and then dropped it. That distinction matters when you are tuning a connection pool or diagnosing a reconnect storm, and it is exactly the gap tproxy targets. The README's motivation section lists three cases the author had in mind: monitoring gRPC connections to see when they connect and reconnect, monitoring MySQL connection pools to count connections and understand the lifetime policy, and monitoring arbitrary TCP connections on the fly. The audience is therefore backend developers, particularly Go developers working in the go-zero ecosystem, who already know which host and port they care about and want a readable stream of events rather than a .pcap file. The tool is a relay, not a capture driver, so it needs the client to talk to tproxy instead of the real server. That constraint shapes everything else about it.

How the relay works, and what the protocol flag changes

The repository layout is compact and readable: conn.go handles a connection, delayedwriter.go implements the -d delay, counter.go and stat.go track byte counts, and protocol/ holds the per-protocol decoders. The flow is a plain TCP proxy. tproxy listens on -l and -p, accepts a client connection, dials -r, and copies bytes in both directions. The -t flag selects a decoder that inspects the stream as it passes: the help text says the supported values are http2, grpc, redis and mongodb. With -t grpc the output is framed around HTTP/2 streams, which is what makes gRPC connection timing legible; without -t, the tool still relays and still reports connection open and close events, but it does not interpret the payload. Two optional layers sit on top of the relay. The -d duration flag delays packets, which is useful for reproducing a slow link. The -up and -down flags cap throughput in bytes per second, using the juju/ratelimit dependency listed in go.mod. The -q flag reduces output to connection open/close and statistics, and -s enables statistics. The stat_linux.go and tcpstat_linux.go files, plus a stat+polyfill.go fallback, indicate that the richer TCP statistics are Linux-specific and that other platforms get a reduced implementation. The README does not spell out which statistics are unavailable off Linux, so treat the retransmission and RTT numbers as a Linux feature until you check on your own machine.

Installing tproxy and running a first gRPC capture

The README gives three install paths. The simplest is the Go toolchain, which requires Go 1.25.0 or later per go.mod. The command below fetches the latest tagged module and places the binary in your Go bin directory; after it finishes, `tproxy --help` should print the flag list quoted in the README.

go install github.com/kevwan/tproxy@latest

If you prefer containers, the README shows a docker run invocation that publishes the listen port and the remote port and passes the same flags to the tproxy binary inside the image. Note the host.docker.internal hostname in the remote address: it is how the container reaches a service on the Docker host.

docker run --rm -it -p <listen-port>:<listen-port> -p <remote-port>:<remote-port> kevinwan/tproxy:v1 tproxy -l 0.0.0.0 -p <listen-port> -r host.docker.internal:<remote-port>

On Windows, the README points to scoop and the single command `scoop install tproxy`. With the binary in place, the first real use is the gRPC example from the README. It listens on port 8088 on localhost, forwards to a gRPC server on 8081, decodes the HTTP/2 frames, and adds 100ms of delay to each packet so the timing is visible in the output.

tproxy -p 8088 -r localhost:8081 -t grpc -d 100ms

Point your client at localhost:8088 instead of 8081 and you should see connection events and per-stream activity in the terminal. The same pattern works for MySQL: `tproxy -p 3307 -r localhost:3306` forwards 3307 to a database on 3306. Adding `-s -q` to that command, as the README's connection-reliability example does, switches to a quiet statistics view intended for retransmission rate and RTT.

Where tproxy stops being the right tool

The relay model is the main limitation. Because tproxy has to be the address the client connects to, it cannot observe a connection that the client opens directly to the server, and it cannot see traffic from processes you cannot reconfigure. The README does not document any transparent interception, iptables integration, or TUN device, and the repository contains no code for them. If you need to capture traffic from an unmodified client on the same host, a packet capture tool is the correct instrument, not this. TLS is the second boundary. The protocol decoders in the protocol/ directory work on the stream as delivered; if the client speaks TLS to the server, the relay sees ciphertext, and the README does not claim any TLS interception capability. A gRPC service configured with TLS will therefore show connection timing but not readable frames. Third, the protocol list is short: http2, grpc, redis and mongodb. Anything else is relayed as opaque bytes. Fourth, the delay flag applies to packets in the relay path, so enabling -d changes the very timing you are trying to measure; use it to reproduce a condition, not to observe a healthy one. Finally, the statistics path is partly platform-specific, as the stat_linux.go and stat+polyfill.go split suggests, so a retransmission figure that appears on Linux may simply be absent elsewhere.

How tproxy differs from tcpdump and from a transparent proxy

The natural comparison is tcpdump, and the difference is where the work happens. tcpdump reads packets from a capture interface and leaves reassembly, protocol decoding and connection tracking to you and to Wireshark. tproxy terminates a TCP connection, so it already has the byte stream in order, and the -t flag turns that stream into protocol-level events. You give up the ability to see traffic you did not route through it, and you gain a readable, per-connection view with no capture privileges and no pcap post-processing. The second comparison is with transparent proxies, which is what most search traffic about the word tproxy is actually about. A transparent proxy intercepts connections the client never redirected, typically through kernel facilities, and is used for network-level routing. kevwan/tproxy does none of that: it is an explicit, opt-in relay you point a client at. That makes it far simpler to reason about and useless for intercepting a device you do not control. If your requirement is system-wide interception, this project is the wrong category of tool, and no flag in the help output changes that.

Maintenance, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-07-09, which is recent. The release history shows v0.9.0 in March 2025, v0.9.1 in July 2025 and v0.9.2 in December 2025, so the project is still tagged, though the interval between v0.9.1 and v0.9.2 was roughly five months. The version numbers have stayed in the 0.9.x range across those releases, which is worth noting if you plan to depend on the CLI's output format: nothing in the README promises that the printed columns are stable across versions, and a minor bump could rearrange them. Upgrading is cheap in the Go case, since `go install github.com/kevwan/tproxy@latest` pulls the newest tag, but that also means an unpinned binary can change under you. The Docker image is tagged v1 and v1-arm64 rather than by release version, so pulling the image again may give you a different build than the one you validated. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code; the repository ships a LICENSE file at the top level. This is a description of the licence identifier, not legal advice, and if you redistribute the binary you should read the LICENSE file yourself.

Editorial conclusion

Adopt tproxy when you need to watch one TCP conversation from the application side and you control the client's target address: a gRPC stub, a MySQL pool, a Redis client. Do not adopt it when the traffic cannot be redirected to a listening port, when you need TLS payload contents, or when you want a system-wide transparent proxy; the repository implements none of those. Before relying on it, verify that the -t value you need exists (the help text lists http2, grpc, redis and mongodb), that -s works on your platform given the stat_linux.go and tcpstat_linux.go split, and that the v1 and v1-arm64 Docker tags match the release you intend to run.

Frequently asked questions

Official sources

1. kevwan/tproxy on GitHub
2. License: MIT
3. Project website
4. README
5. Releases