{"id":18686735,"url":"https://github.com/wayfair-incubator/minigun","last_synced_at":"2025-04-12T05:07:46.148Z","repository":{"id":39243798,"uuid":"433102870","full_name":"wayfair-incubator/minigun","owner":"wayfair-incubator","description":"Simple HTTP benchmark tool ","archived":false,"fork":false,"pushed_at":"2024-05-28T08:31:39.000Z","size":944,"stargazers_count":23,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-28T21:18:32.805Z","etag":null,"topics":["benchmark","golang","hacktoberfest","http","kubernetes","metrics","performance-testing"],"latest_commit_sha":null,"homepage":"","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/wayfair-incubator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-29T15:47:50.000Z","updated_at":"2024-06-03T16:04:02.116Z","dependencies_parsed_at":"2023-11-06T11:46:58.321Z","dependency_job_id":"cf845eb3-eb7d-40aa-9ec1-79d230b1bea6","html_url":"https://github.com/wayfair-incubator/minigun","commit_stats":{"total_commits":52,"total_committers":6,"mean_commits":8.666666666666666,"dds":0.4807692307692307,"last_synced_commit":"826eaef38c285f93c76c2f4da651db1c778bd30f"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":"wayfair-incubator/oss-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair-incubator%2Fminigun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair-incubator%2Fminigun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair-incubator%2Fminigun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayfair-incubator%2Fminigun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wayfair-incubator","download_url":"https://codeload.github.com/wayfair-incubator/minigun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519545,"owners_count":21117761,"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":["benchmark","golang","hacktoberfest","http","kubernetes","metrics","performance-testing"],"created_at":"2024-11-07T10:28:47.847Z","updated_at":"2025-04-12T05:07:46.133Z","avatar_url":"https://github.com/wayfair-incubator.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minigun\n\n[![Minigun Version](https://img.shields.io/badge/Minigun-0.6.1-7f187f.svg)](https://github.com/wayfair-incubator/minigun/blob/main/CHANGELOG.md)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)\n\n## About The Project\n\nMinigun is a highly performant Kubernetes native HTTP benchmark tool written in Go.\nBesides providing a text or JSON report, it exposes metrics in Prometheus format,\nwhich could be scraped from the Minigun's `/metrics` endpoint or pushed to the\nPrometheus Push Gateway.\n\nIt can be run as a CLI tool on any supported system to run a benchmark, as a Pod inside\nKubernetes cluster to constantly provide performance metrics, or as a one time Job.\n\n## Getting Started\n\nBinary:\n\n1. Download a tarball from the [releases](https://github.com/wayfair-incubator/minigun/releases) page.\n1. Unpack it, example for Linux binary: `tar xzf minigun-linux64.tgz`\n1. Run it: `./minigun -h`\n\nDocker image:\n\n1. Check [available docker image tags](https://github.com/wayfair-incubator/minigun/pkgs/container/minigun/versions)\n1. Download the image: `docker pull ghcr.io/wayfair-incubator/minigun:latest`\n1. Run it: `docker run --rm ghcr.io/wayfair-incubator/minigun:latest -h`\n\n## Usage\n\n### Simple examples\n\nRunning a test with 50 reqs/sec rate for 30 seconds and sending 5Kb body via `POST`:\n\n```sh\nminigun \\\n  -fire-target http://kube-echo-perf-test.test.cluster.local/echo/2 \\\n  -send-method POST -random-body-size 5Kb \\\n  -fire-rate 50 -workers 20 -fire-duration 30s\n```\n\nResult:\n\n```plain text\nStarting benchmark\nBenchmark is running.\nBenchmark is complete.\n\nTarget:                              http://kube-echo-perf-test.test.cluster.local/echo/2\nMethod:                              POST\nDuration:                            30.00 seconds\nMax concurrency:                     20\nRequest body size:                   5.0 kB\n\nCompleted requests:                  1517\nSucceeded requests:                  1517\nFailed requests:                     0\nRequests per second:                 50.57 (mean, across all concurrent requests)\nTransfer rate (HTTP Message Body)    319 kB/s sent (mean)\n                                     253 kB/s sent (mean, across all concurrent requests)\n                                     637 kB/s received (mean)\n                                     506 kB/s received (mean, across all concurrent requests)\nDNS queries                          20\nTCP connections                      20\nHTTP status codes                    [200:1517]\n\n                           MEAN       MEDIAN      P90        P95        P99\nFull request duration      15.69ms    15.74ms     16.70ms    16.86ms    31.42ms\nDNS request duration       3.46ms     742.81µs    17.48ms    19.31ms    19.39ms\nTCP connection duration    14.28ms    14.30ms     15.10ms    15.30ms    15.86ms\nHTTP write request body    41.12µs    39.05µs     50.61µs    56.17µs    76.90µs\nHTTP time to first byte    15.61ms    15.65ms     16.63ms    16.78ms    31.36ms\nHTTP response duration     15.34ms    15.59ms     16.56ms    16.70ms    17.34ms\n```\n\nRunning a test via HTTPS with custom `Host` header and interrupting it in the middle:\n\n```sh\nminigun \\\n  -insecure -fire-target https://10.10.10.10/echo/2 \\\n  -http-header Host:kube-echo-perf-test.test.cluster.local \\\n  -send-method POST -random-body-size 5Kb \\\n  -fire-rate 20 -workers 20 -fire-duration 30s\n```\n\nResult:\n\n```plain text\nStarting benchmark\nBenchmark is running.\n^C\nReceived signal: interrupt\nBenchmark is complete.\n\nTarget:                              https://10.10.10.10/echo/2\nMethod:                              POST\nDuration:                            10.96 seconds\nMax concurrency:                     20\nRequest body size:                   5.0 kB\n\nCompleted requests:                  222\nSucceeded requests:                  222\nFailed requests:                     0\nRequests per second:                 20.25 (mean, across all concurrent requests)\nTransfer rate (HTTP Message Body)    279 kB/s sent (mean)\n                                     101 kB/s sent (mean, across all concurrent requests)\n                                     558 kB/s received (mean)\n                                     202 kB/s received (mean, across all concurrent requests)\nTCP connections                      20\nTLS Handshakes                       20\nHTTP status codes                    [200:222]\n\n                           MEAN       MEDIAN     P90        P95        P99\nFull request duration      17.94ms    15.43ms    17.01ms    44.79ms    48.32ms\nTCP connection duration    13.86ms    13.94ms    14.82ms    15.04ms    15.11ms\nTLS handshake duration     16.04ms    15.99ms    17.01ms    17.16ms    21.86ms\nHTTP write request body    69.15µs    62.11µs    81.12µs    87.90µs    126.59µs\nHTTP time to first byte    17.85ms    15.35ms    16.92ms    44.71ms    48.23ms\nHTTP response duration     15.06ms    15.20ms    16.13ms    16.32ms    17.02ms\n```\n\nSince we're using IP address and `https://` scheme in this second example, please note\nthat DNS metrics are no longer reported but instead we have new TLS related metrics.\n\nOne more example for JSON report:\n\n```sh\nminigun \\\n  -fire-target http://kube-echo-perf-test.test.cluster.local/ \\\n  -fire-rate 50 -workers 20 -fire-duration 15s -report json | jq '.RequestsCompleted'\n\n759\n```\n\n### Pushing metrics to Prometheus Pushgateway\n\nIn this example we're running Minigun on one of the Kubernettes nodes and we're pushing\nmetrics to the Prometheus Pushgateway endpoint (ClusterIP Kubernetes service)\n\n```sh\nminigun \\\n  -fire-target http://kube-echo-perf-test.test.cluster.local/echo/2 \\\n  -fire-rate 20 -fire-duration 10m -insecure -workers 20 \\\n  -disable-keep-alive -send-method POST -random-body-size 1Kb \\\n  -push-gateway http://192.168.0.1:9091 -name ssl-test\n```\n\nPlease note that you can add `-name YOUR_NAME_HERE` argument to set custom `name`\nlabel value for metrics exported to Prometheus. This could be useful to separate your\ntest metrics from others.\n\n## Understanding report\n\n[![minigun metrics](docs/images/minigun-metrics.png)](docs/images/minigun-metrics.svg)\n\nYou can read detailed explanation of reported metrics by using CLI help:\n\n```sh\nminigun -report-help\n```\n\nOr by checking the [following documentation page](./docs/report-help.md)\n\n### Grafana Dashboard\n\nChart examples from [Minigun Grafana dashboard](grafana/Minigun.json):\n![minigun grafana main](docs/images/minigun_main_grafana.png)\n![minigun grafana tcp and dns](docs/images/minigun_tcp_dns_grafana.png)\n\nPlease note that this dashboard was designed for a multi-cluster environment in which\nevery cluster has a unique `cluster_name` label on every metric, which is implemented\nvia Prometheus `global.external_labels` [config option](https://prometheus.io/docs/prometheus/latest/configuration/configuration/).\n\n## Local Development\n\n### Prerequisites\n\nThis is an example of how to list things you need to use the software and how to install them.\n\n- Docker for image build.\n- Golang 1.22 for local binary build.\n\n### Building a Docker image\n\n```sh\ndocker-compose build\n```\n\nor\n\n```sh\ndocker build .\n```\n\n### Building a local binary\n\nIf you want to `go run` or build locally with your system Golang instead of docker,\nyou need to do this:\n\n1. Put this app  directory to your `$GOPATH` (if env is not set you can check with `go env`):\n\n   ```sh\n   cp -a ./  ~/go/src/github.com/wayfair-incubator/minigun\n   ```\n\n1. Go to your working directory:\n\n   ```sh\n   cd ~/go/src/github.com/wayfair-incubator/minigun\n   ```\n\n1. Edit files.\n\n1. Create vendor to speed up re-builds (it will be also used if you build in Docker):\n\n   ```sh\n   make get-deps\n   ```\n\n1. Build binary for your local OS:\n\n   ```sh\n   make local-build\n   ```\n\n1. Run it:\n\n   ```sh\n   ./minigun -h\n   ```\n\n## Roadmap\n\nSee the [open issues](https://github.com/wayfair-incubator/minigun/issues) for a list of proposed features (and known issues).\n\n## Release Management\n\n- Push changes via Github Pull Requests, review and merge them.\n- Change the version constant in the `main.go` file.\n- Add all changes introduced since the last release to the `CHANGELOG.md` file.\n- When the new release is ready, [draft a new release](https://github.com/wayfair-incubator/minigun/releases/new):\n  - Make sure to specify a new tag, make sure to follow [SemVer spec](https://semver.org/spec/v2.0.0.html).\n- Publish the new release.\n- All artifacts should be published automatically shortly after the new release is published.\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. For detailed contributing guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\nDistributed under the `MIT` License. See `LICENSE` for more information.\n\n## Contact\n\nAlexander Didenko - [@adidenko](https://github.com/adidenko)\n\nProject Link: [https://github.com/wayfair-incubator/minigun](https://github.com/wayfair-incubator/minigun)\n\n## Acknowledgements\n\nThis template was adapted from\n[https://github.com/othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayfair-incubator%2Fminigun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwayfair-incubator%2Fminigun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayfair-incubator%2Fminigun/lists"}