TLDR . Description . Usage . Execution using Docker . Installation . Help . Examples . Extra project information . Why do I want to test TCP connections? . Where does the project name come from? . Authors . Especial thanks to... . Development information . TO-DO . Project structure . README maintenance . Testing locally .
Tool to test concurrent connections towards a server listening to a TCP port
- Given a hostname, port, the number of connections (100 by default), a delay between connections (10ms by default) and an interval between stats updates to the standard output...
- It will use goroutines to open TCP connections and try to read from them
- The tool will exit once all connections have been dialed (successfully or not)
- Exit status different from 0 represent executions where all connections were not established successfully, facilitating the integration in test suites.
See our public docker image and its documentation. The image is being updated continuously; you can bind to specific versions, or to the "latest" tag.
% go get github.com/dachad/tcpgoon% tcpgoon --help
tcpgoon tests concurrent connections towards a server listening on a TCP port
Usage:
tcpgoon [command]
Available Commands:
help Help about any command
run Run tcpgoon test
version Show tcpgoon version
Flags:
-h, --help help for tcpgoon
Use "tcpgoon [command] --help" for more information about a command.
% tcpgoon run --help
Run tcpgoon test
Usage:
tcpgoon run [flags] <host> <port>
Flags:
-y, --assume-yes Force execution without asking for confirmation
-c, --connections int Number of connections you want to open (default 100)
-d, --debug Print debugging information to the standard error
-t, --dial-timeout int Connection dialing timeout, in ms (default 5000)
-h, --help help for run
-i, --interval int Interval, in seconds, between stats updates (default 1)
-s, --sleep int Time you want to sleep between connections, in ms (default 10)Note: depending on the number of connections you want to open, you may need to increase the number of file descriptors your user supports
Successful execution (connections were opened as expected):
% tcpgoon run myhttpsamplehost.com 80 --connections 4 --sleep 999 -y
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 0, NotInitiated: 4
Total: 4, Dialing: 1, Established: 1, Closed: 0, Error: 0, NotInitiated: 2
Total: 4, Dialing: 1, Established: 2, Closed: 0, Error: 0, NotInitiated: 1
Total: 4, Dialing: 1, Established: 3, Closed: 0, Error: 0, NotInitiated: 0
Total: 4, Dialing: 0, Established: 4, Closed: 0, Error: 0, NotInitiated: 0
--- myhttpsamplehost.com(216.58.201.131):80 tcp test statistics ---
Total: 4, Dialing: 0, Established: 4, Closed: 0, Error: 0, NotInitiated: 0
--- tcpgoon execution statistics ---
Total established connections: 4
Max concurrent established connections: 4
Number of established connections on closure: 4
Response time stats for 4 successful connections min/avg/max/dev = 49.892ms/50.205ms/50.74ms/319µs
% echo $?
0Unsuccessful execution (unable to open connections against the destination host:port):
% tcpgoon run myhttpsamplehost.com 81 --connections 4 --sleep 999 -t 1 -y
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 0, NotInitiated: 4
Total: 4, Dialing: 1, Established: 0, Closed: 0, Error: 1, NotInitiated: 2
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 3, NotInitiated: 1
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 4, NotInitiated: 0
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 4, NotInitiated: 0
--- myhttpsamplehost.com(216.58.201.131):81 tcp test statistics ---
Total: 4, Dialing: 0, Established: 0, Closed: 0, Error: 4, NotInitiated: 0
--- tcpgoon execution statistics ---
Total established connections: 0
Max concurrent established connections: 0
Number of established connections on closure: 0
Time to error stats for 4 failed connections min/avg/max/dev = 1ms/1.122ms/1.165ms/37µs
% echo $?
2Stressing TCP connections against a server/application facilitates the detection of bottlenecks/issues limiting the capacity of this server/application to accept/keep a specific (and potentially) large number of parallel connections. Some examples of typical (configuration) issues:
- OS configuration (TCP backlog, network drivers buffers),
- number of file descriptors/processes the server can use,
- application listener properties...
These limitations may pass unnoticed in actual application-l7 stress tests, given other bottlenecks can arise earlier than these limitations, or degradation scenarios and/or special conditions may not be reproduced during the stress tests execution, but in real life (lots of connections queued because of a dependency taking longer to reply than it usually does?)
hping is not an actual option for this use case given it won't complete a 3-way handshake, so the connection will not reach the accept() syscall of your server/application or fill up your TCP backlog.
Goon: /ɡuːn/ noun informal; noun: goon; plural noun: goons ;
...
2.
NORTH AMERICAN
a bully or thug, especially a member of an armed or security force.
...
- Linafm design, for our custom and nice Goon Gopher
We do use Github issues to track bugs, improvements and feature requests. Do not hesitate to raise new ones, or solve them for us by raising PRs ;)
This project uses a layered topology, where cmd (complemented by cmdutil) takes care of commands/flags/arguments and uses mtcpclient, which owns and knows everything about "multiple TCP connections" (including reporting), while tcpclient only cares about managing single TCP connections. tcpserver is just there as a dependency for the other packages' tests.
A shared package (debugging) is also supplied just as a basic mechanism to control debug output.
Do not edit README.md directly, as your changes will be lost. Consider README.src.md and the execution (requires godepgraph and Graphviz) of:
% ./_script/readme_generatorSamples injected in the readme can be found in the _script/readme_generator_samples/ directory.
Dockerhub README requires manual maintenance, bringing relevant aspects from here and adapting cmdusage (by docker run...)
You can use the standard go test command, or use our scripts we also run as CI.
Main tests execution:
% ./_script/testEmulation of a travis job execution using docker (of course, it needs docker):
% COVERALLS_TOKEN="myToken" ./_script/cibuild-dockerAnd also emulating a travis job deployment (it publishes new binaries providing successful tests and the right credentials, unless you also use the -r flag / dry-run):
% COVERALLS_TOKEN="myToken" ./_script/cibuild-docker -d