{"id":15209458,"url":"https://github.com/twentyone24/maelstrom","last_synced_at":"2025-10-29T15:30:39.714Z","repository":{"id":249481345,"uuid":"831633608","full_name":"twentyone24/maelstrom","owner":"twentyone24","description":"stress-test your API reliability on concurrent threads, with latency metrics.","archived":false,"fork":false,"pushed_at":"2024-08-25T09:49:00.000Z","size":37,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-02T02:01:47.393Z","etag":null,"topics":["api","bash","bash-script","linux-shell","load-testing","script","shell","shell-script","testing-tools","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/twentyone24.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-21T06:48:33.000Z","updated_at":"2024-09-13T16:29:08.000Z","dependencies_parsed_at":"2024-07-21T08:33:32.789Z","dependency_job_id":"11a5d8af-3c7b-41ba-9094-f372ab1c9fbd","html_url":"https://github.com/twentyone24/maelstrom","commit_stats":null,"previous_names":["twentyone24/maelstrom"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twentyone24%2Fmaelstrom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twentyone24%2Fmaelstrom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twentyone24%2Fmaelstrom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twentyone24%2Fmaelstrom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twentyone24","download_url":"https://codeload.github.com/twentyone24/maelstrom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238840723,"owners_count":19539602,"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":["api","bash","bash-script","linux-shell","load-testing","script","shell","shell-script","testing-tools","zsh"],"created_at":"2024-09-28T07:40:19.537Z","updated_at":"2025-10-29T15:30:34.427Z","avatar_url":"https://github.com/twentyone24.png","language":"Shell","funding_links":[],"categories":["\u003ca name=\"webdev\"\u003e\u003c/a\u003eWeb development"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"maelstromlogo\" src=\"https://github.com/user-attachments/assets/3f1a6cf1-95d3-4b57-a133-b5de0ed1410f\"\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n A performant and lightweight stress test tool that uses concurrent threads to test API reliability, with configurable parameters, detailed logging, and email notifications.\n\u003c/div\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.producthunt.com/posts/maelstrom?embed=true\u0026utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-maelstrom\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=478519\u0026theme=light\" alt=\"maelstrom - stress\u0026#0045;test\u0026#0032;your\u0026#0032;API\u0026#0032;reliability\u0026#0032;w\u0026#0047;\u0026#0032;concurrency\u0026#0032; | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cbr/\u003e\n\n\n## ✨ Features\n\n- 🌈 **Configurable Parameters**: Customize the number of requests, concurrency level, URL to test, retry limits, response time thresholds, and success rate thresholds.\n- 💅 **Detailed Logging**: Captures detailed information about each request, including HTTP status codes and response times.\n- 🔥 **Email Notifications**: Optionally sends email notifications with a summary of test results.\n- 🛡 **Graceful Shutdown**: Handles interruptions gracefully, ensuring that results are logged and notifications are sent.\n- 🚀 **Latency Metrics**: Helps understand average latency of APIs helping you understand if the latency increases.\n- 📦 **Multi-threaded by design**: Simulates multi-threaded concurrent requests to API Endpoints w/ configurable thread count.\n\n## 🚀 Prerequisites\n\n- **Curl**: Required for making HTTP requests. Ensure it is installed on your system.\n- **Mail**: Required for sending email notifications (if enabled). Install a mail utility like `mailx` or `sendmail`.\n- **bc**: Required for floating-point arithmetic in shell scripts. Ensure it is installed.\n\n## ⚡️ Configuration\n\n### Configuration File (`maelstrom.conf`)\n\nThe script reads configuration values from `maelstrom.conf`. Here’s an example of how to structure this file:\n\n```bash\n# maelstrom.conf\nN=1000\nTHREADS=10\nURL=https://api.sampleapis.com/coffee/hot\nRETRY_LIMIT=3\nTHRESHOLD_TIME=2.0\nTHRESHOLD_SUCCESS=95\nEMAIL_ENABLED=false\nEMAIL_TO=\n```\n\n### Parameters\n\n- **Number of requests (`N`)**: Total number of HTTP requests to be performed.\n- **Number of concurrent threads (`THREADS`)**: Number of concurrent threads to be used for the load test.\n- **URL to test (`URL`)**: The endpoint URL where the load test will be executed.\n- **Retry limit (`RETRY_LIMIT`)**: Number of retry attempts for failed requests.\n- **Response time threshold (`THRESHOLD_TIME`)**: Maximum acceptable response time in seconds.\n- **Success rate threshold (`THRESHOLD_SUCCESS`)**: Minimum acceptable success rate percentage.\n- **Enable email notifications (`EMAIL_ENABLED`)**: Boolean value to enable or disable email notifications.\n- **Email address for notifications (`EMAIL_TO`)**: Recipient email address for notifications.\n\n## Usage\n\n1. **Prepare the Configuration File**\n\n   Create a `maelstrom.conf` file in the same directory as the script. Set your desired configuration values as described in the [Configuration](#configuration) section.\n\n2. **Run the Script**\n\n   Make the script executable and run it:\n\n   ```bash\n   chmod +x strom.sh\n   ./strom.sh\n   ```\n\n3. **Monitor the Load Test**\n\n   The script will output progress and results to the terminal. You can monitor real-time updates during the test.\n\n4. **Review Results**\n\n   Upon completion, the script will display results including total requests, successful requests, failed requests, average response time, and success rate.\n\n5. **Email Notifications**\n\n   If email notifications are enabled, the script will send an email with the test results to the specified address.\n\n## Handling Interruptions\n\nThe script is designed to handle interruptions gracefully. To stop the test, press `Ctrl+C` or send a termination signal. The script will log the results and send email notifications if configured.\n\n## Example Output\n\n```bash\n███╗   ███╗ █████╗ ███████╗██╗     ███████╗████████╗██████╗  ██████╗ ███╗   ███╗\n████╗ ████║██╔══██╗██╔════╝██║     ██╔════╝╚══██╔══╝██╔══██╗██╔═══██╗████╗ ████║\n██╔████╔██║███████║█████╗  ██║     ███████╗   ██║   ██████╔╝██║   ██║██╔████╔██║\n██║╚██╔╝██║██╔══██║██╔══╝  ██║     ╚════██║   ██║   ██╔══██╗██║   ██║██║╚██╔╝██║\n██║ ╚═╝ ██║██║  ██║███████╗███████╗███████║   ██║   ██║  ██║╚██████╔╝██║ ╚═╝ ██║\n╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝\n\n🔧 Enter configuration values. Press Enter to keep default.\nNumber of requests (default: 1000): 1000\nNumber of concurrent threads (default: 10): 10\nURL to test (default: https://api.sampleapis.com/coffee/hot): https://api.sampleapis.com/coffee/hot\nRetry limit for failed requests (default: 3): 3\nResponse time threshold in seconds (default: 2.0): 2.0\nSuccess rate threshold in percentage (default: 95): 95\nEnable email notifications (true/false, default: false): false\nEmail address for notifications (default: empty):\n\nStarting load test with 1000 requests and 10 threads...\n\n\u003e WARMUP COMPLETE, STARTING UP THE STORM\n\n[Thread  1] Response: 200, Time taken: 0.45s\n[Thread  2] Response: 500, Time taken: 1.22s\n...\n\n========================================\nRESULTS:\n- Total requests:          1000\n- Successful requests:     950\n- Failed requests:         50\n- Average response time:   1.35 seconds\n- Success rate:            95%\n\n- Average response time is within the acceptable range. 👍\n- Success rate meets the threshold. ✔️\n========================================\n```\n\n## Troubleshooting\n\n- **Mail Command Not Found**: Install a mail utility like `mailx` or `sendmail` for email notifications.\n\n## License\n\nThis script is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwentyone24%2Fmaelstrom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwentyone24%2Fmaelstrom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwentyone24%2Fmaelstrom/lists"}