{"id":13393157,"url":"https://github.com/goadapp/goad","last_synced_at":"2025-09-28T23:32:33.360Z","repository":{"id":45791825,"uuid":"50202399","full_name":"goadapp/goad","owner":"goadapp","description":"Goad is an AWS Lambda powered, highly distributed, load testing tool","archived":true,"fork":false,"pushed_at":"2020-04-23T18:16:47.000Z","size":26343,"stargazers_count":1884,"open_issues_count":34,"forks_count":190,"subscribers_count":54,"default_branch":"master","last_synced_at":"2024-09-23T09:09:49.677Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://goad.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goadapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-22T19:21:26.000Z","updated_at":"2024-09-10T14:53:31.000Z","dependencies_parsed_at":"2022-07-17T00:30:43.373Z","dependency_job_id":null,"html_url":"https://github.com/goadapp/goad","commit_stats":null,"previous_names":["gophergala2016/goad"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadapp%2Fgoad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadapp%2Fgoad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadapp%2Fgoad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadapp%2Fgoad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goadapp","download_url":"https://codeload.github.com/goadapp/goad/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234575214,"owners_count":18854924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:00:44.280Z","updated_at":"2025-09-28T23:32:28.298Z","avatar_url":"https://github.com/goadapp.png","language":"Go","funding_links":[],"categories":["Go","Open Source Repos","AWS Lambda Functions"],"sub_categories":["Lambda"],"readme":"# Goad\n\n\u003chttps://goad.io\u003e\n\nGoad is an AWS Lambda powered, highly distributed,\nload testing tool built in Go for the 2016 [Gopher Gala][].\n\n![Go + Load ⇒ Goad](https://goad.io/assets/go-plus-load.png)\n\nGoad allows you to load test your websites from all over the world whilst costing you the tiniest fractions of a penny by using AWS Lambda in multiple regions simultaneously.\n\nYou can run Goad from your machine using your own AWS credentials. Goad will automatically create the AWS resources you need and execute your test, and display the results broken down by region. This way, you can see how fast your website is from the major regions of the world.\n\nIf you just want to try Goad out, visit the [Goad.io website](https://goad.io) and enter the address of the site you want to test.\n\n![goad CLI interface](https://goad.io/assets/cli.gif)\n\n## Installation\n\n### Binary\n\nThe easiest way is to download a pre-built binary from [Goad.io] or from the [GitHub Releases][] page.\n\n### From source\n\nTo build the Goad CLI from scratch, make sure you have a working Go 1.5 workspace ([instructions](https://golang.org/doc/install)), then:\n\n\n1. Fetch the project with `go get`:\n\n  ```sh\n  go get github.com/goadapp/goad\n  ```\n\n2. Install Go [bindata][]:\n\n  ```sh\n  go get -u github.com/jteeuwen/go-bindata/...\n  ```\n\n3. Run make to build for all supported platforms\n\n  ```sh\n  make\n  ```\n\n  Alternatively, run append `osx`, `linux`, or `windows` to just build for one platform, for example:\n\n  ```sh\n  make osx\n  ```\n\n4. You'll find your `goad` binary in the `build` folder…\n\n## Usage\n\n### AWS credentials\n\nGoad will read your credentials from `~/.aws/credentials` or from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables ([more info](http://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs)).\n\n### CLI\n\n```\n# Get help:\n$ goad --help\nusage: goad [\u003cflags\u003e] [\u003curl\u003e]\n\nAn AWS Lambda powered load testing tool\n\nFlags:\n  -h, --help                     Display usage information (this message)\n  -n, --requests=2000            Number of requests to perform. Set to 0 in combination with a specified timelimit allows for unlimited requests for the specified time.\n  -c, --concurrency=10           Number of multiple requests to make at a time\n  -t, --timelimit=3600           Seconds to max. to spend on benchmarking\n  -s, --timeout=15               Seconds to max. wait for each response\n  -H, --header=HEADER ...        Add Arbitrary header line, eg. 'Accept-Encoding: gzip' (repeatable)\n  -m, --method=\"GET\"             HTTP method\n      --body=BODY                HTTP request body\n      --json-output=JSON-OUTPUT  Optional path to file for JSON result storage\n      --region=us-east-1 ...     AWS regions to run in. Repeat flag to run in more then one region. (repeatable)\n      --run-docker               execute in docker container instead of aws lambda\n      --create-ini-template      create sample configuration file \"goad.ini\" in current working directory\n  -V, --version                  Show application version.\n\nArgs:\n  [\u003curl\u003e]  [http[s]://]hostname[:port]/path optional if defined in goad.ini\n\n# For example:\n$ goad -n 1000 -c 5 https://example.com\n```\n\nNote that sites such as https://google.com that employ redirects cannot be tested correctly at this time.\n\n### Settings\n\nGoad supports to load settings stored in an ini file. It looks\nfor a goad.ini file in the current working directory. Flags set on the command-line will\nbe overwrite these settings.\n\n```ini\n[general]\n#url = http://example.com/\ntimeout = 3600\nconcurrency = 10\nrequests = 1000\ntimelimit = 15\njson-output = test-result.json\nmethod = GET\nbody = Hello world\n\n[regions]\nus-east-1 ;N.Virginia\n#us-east-2 ;Ohio\n#us-west-1 ;N.California\n#us-west-2 ;Oregon\neu-west-1 ;Ireland\n#eu-central-1 ;Frankfurt\n#ap-southeast-1 ;Singapore\n#ap-southeast-2 ;Sydney\n#ap-northeast-1 ;Tokyo\n#ap-northeast-2 ;Seoul\n#sa-east-1 ;Sao Paulo\n\n[headers]\ncache-control: no-cache\nauth-token: YOUR-SECRET-AUTH-TOKEN\n```\n\n### Docker\n\nGoad can also be run as a Docker container which exposes the web API:\n\n    docker build -t goad .\n    docker run --rm -p 8080:8080 -e AWS_ACCESS_KEY_ID=\u003cyour key ID\u003e -e AWS_SECRET_ACCESS_KEY=\u003cyour key\u003e goad\n\nYou can then execute a load test using WebSocket:\n\n    ws://localhost:8080/goad?url=https://example.com\u0026requests=1000\u0026concurrency=10\u0026timelimit=3600\u0026timeout=15\u0026region[]=us-east-1\u0026region[]=eu-west-1\n\n## How it works\n\nGoad takes full advantage of the power of Amazon Lambdas and Go's concurrency for distributed load testing. You can use Goad to launch HTTP loads from up to four AWS regions at once. Each lambda can handle hundreds of concurrent connections, we estimate that Goad should be able to achieve peak loads of up to **100,000 concurrent requests**.\n\n![Goad diagram](https://goad.io/assets/diagram.svg)\n\nRunning Goad will create the following AWS resources:\n\n- An IAM Role for the lambda function.\n- An IAM Role Policy that allows the lambda function to send messages to SQS, to publish logs and to spawn new lambda in case an individual lambda times out on a long running test.\n- A lambda function.\n- An SQS queue for the test.\n\nA new SQS queue is created for each test run, and automatically deleted after the test is completed. The other AWS resources are reused in subsequent tests.\n\n## How it was built\n\n### Go CLI and server\n\n* [AWS SDK for Go][]\n* [Gorilla WebSocket][]\n* [Termbox][]\n* [UUID][]\n* [bindata][]\n\n### Goad executable\n\nWritten in pure Go, Goad takes care of instantiating all the AWS resources, collecting results and displaying them. Interestingly, it contains the executable of the Lambda worker, which is also written in Go.\n\nThere is also a webapi version, which can be used to serve Goad as a web service. This streams the results using WebSockets.\n\n### Lambda workers\n\nAWS Lambda instances are bootstrapped using node.js but the actual work on the Lambda instances is performed by a Go process. The HTTP\nrequests are distributed among multiple Lambda instances each running multiple concurrent goroutines, in order to achieve the desired\nconcurrency level with high throughput.\n\n## License \u0026 Copyright\n\nMIT License. \u003cbr/\u003e\nCopyright 2016 [Joao Cardoso][], [Matias Korhonen][], [Rasmus Sten][], and [Stephen Sykes][]. \u003cbr/\u003e\nCopyright 2016 Guido Serra [OLX, a Naspers company](http://joinolx.com). \u003cbr/\u003e\nCopyright 2017 Walter Marta, Clemens Wältken [Edrans/OLX](http://edrans.com).\n\nSee the LICENSE file for more details.\n\n[Goad.io]: https://goad.io\n[GitHub Releases]: https://github.com/gophergala2016/goad/releases\n\n[AWS SDK for Go]: http://aws.amazon.com/sdk-for-go/\n[Gorilla WebSocket]: https://github.com/gorilla/websocket\n[Termbox]: https://github.com/nsf/termbox-go\n[UUID]: https://github.com/satori/go.uuid\n[bindata]: https://github.com/jteeuwen/go-bindata\n[toml]: https://github.com/toml-lang/toml\n\n[Gopher Gala]: http://gophergala.com/\n[Joao Cardoso]: https://twitter.com/jcxplorer\n[Matias Korhonen]: https://twitter.com/matiaskorhonen\n[Rasmus Sten]: https://twitter.com/pajp\n[Stephen Sykes]: https://twitter.com/sdsykes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoadapp%2Fgoad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoadapp%2Fgoad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoadapp%2Fgoad/lists"}