{"id":19468796,"url":"https://github.com/imrafaelmerino/mighty-meter","last_synced_at":"2025-07-30T21:07:38.365Z","repository":{"id":261787853,"uuid":"885318797","full_name":"imrafaelmerino/mighty-meter","owner":"imrafaelmerino","description":"MightyMeter is a simple yet powerful solution for distributed performance testing with JMeter, featuring real-time monitoring via Grafana and InfluxDB. With an easy Docker setup, it streamlines scalable testing and displays key metrics on intuitive dashboards, making it effortless to analyze and optimize application performance at scale.","archived":false,"fork":false,"pushed_at":"2024-11-24T12:59:30.000Z","size":8198,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T19:56:49.883Z","etag":null,"topics":["apdex","cli-mode","distributed-testing","docker","generator","grafana","grafana-dashboard","influxdb","jmeter","json-generator"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imrafaelmerino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-11-08T11:04:12.000Z","updated_at":"2025-03-28T08:58:11.000Z","dependencies_parsed_at":"2024-11-08T13:18:40.778Z","dependency_job_id":"0479fd71-28ff-4f6a-acf4-2bcc7f5183cd","html_url":"https://github.com/imrafaelmerino/mighty-meter","commit_stats":null,"previous_names":["imrafaelmerino/mighty-meter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/imrafaelmerino/mighty-meter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fmighty-meter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fmighty-meter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fmighty-meter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fmighty-meter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imrafaelmerino","download_url":"https://codeload.github.com/imrafaelmerino/mighty-meter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fmighty-meter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263468197,"owners_count":23471232,"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":["apdex","cli-mode","distributed-testing","docker","generator","grafana","grafana-dashboard","influxdb","jmeter","json-generator"],"created_at":"2024-11-10T18:43:56.523Z","updated_at":"2025-07-04T07:32:43.059Z","avatar_url":"https://github.com/imrafaelmerino.png","language":"Shell","funding_links":["https://www.buymeacoffee.com/imrafaelmerino"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./image/logo.png\" alt=\"Logo\" width=\"300\" height=\"300\" /\u003e\n\u003c/p\u003e\n\n“_Power Meets Simplicity in Just Three Clicks_”\n\n[![GitHub release](https://img.shields.io/github/v/release/imrafaelmerino/mighty-meter?include_prereleases\u0026label=Latest%20Release)](https://github.com/imrafaelmerino/mighty-meter/releases/latest)\n\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-%E2%98%95%20Support-yellow)](https://www.buymeacoffee.com/imrafaelmerino)\n\n# MightyMeter\n\n- [Introduction](#intro)\n- [Requirements](#req)\n- [Installation of the Leader](#leader-install)\n- [Installation of the Workers](#worker-install)\n- [Configuring Your JMX File](#jmx-config)\n- [Running Tests](#running-tests)\n- [Grafana Dashboards](#grafana-dashboards)\n- [Querying the Database](#querying-db)\n- [Additional Commands](#additional-commands)\n- [Generating Data](#generators)\n\n## \u003ca name=\"intro\"\u003e\u003c/a\u003e Introduction\n\nMightyMeter is a powerful performance testing solution that leverages\n[InfluxDB](https://www.influxdata.com/), [Grafana](https://grafana.com/), and\n[JMeter](https://jmeter.apache.org/) to support both local and distributed testing modes. Here’s a\ncloser look at its two operational modes:\n\n### 1. Local CLI Mode\n\nIn local testing, it’s recommended to run JMeter in CLI (Command Line Interface) mode instead of the\nGUI. The CLI mode is more efficient for executing tests and conserving resources, which makes it\nideal for performance evaluation. While JMeter’s GUI mode is highly useful for creating and\nmodifying `.jmx` test files, the CLI mode ensures stable, reliable execution when running actual\ntests.\n\n### 2. Distributed Testing Mode\n\nMightyMeter facilitates a straightforward setup for distributed testing with multiple JMeter\nservers. In this configuration, a central **Leader** node (or master node) coordinates multiple\n**Worker** nodes (or slave nodes). The Leader node distributes the test configurations to each\nWorker, and as the test runs, each Worker sends its results back to the Leader. This mode is\nparticularly valuable for large-scale tests and scenarios requiring load generation from multiple\nlocations or servers.\n\n### Key Features in Both Modes:\n\n- **Result Persistence:** Test results are stored in an InfluxDB database, providing a durable and\n  structured record of performance metrics.\n- **Real-Time Monitoring and Visualization:** MightyMeter integrates with Grafana dashboards to\n  enable real-time test monitoring. These visualizations pull data from InfluxDB and provide\n  insights into various test statistics. Additional dashboards allow you to compare metrics across\n  different application versions, user loads, and other test conditions.\n- **Comprehensive Reporting:** Test reports are generated in both text and HTML formats and include\n  APDEX (Application Performance Index) ratings. Reports are accessible via an HTTP server powered\n  by [NGinx](https://www.nginx.com/), making it easy to review and share performance summaries.\n\nIn summary, MightyMeter offers a flexible testing environment suited to both local and distributed\nload testing needs, with robust support for result persistence, real-time insights, and detailed\nreporting.\n\n## \u003ca name=\"req\"\u003e\u003c/a\u003e Requirements\n\nTo set up the system, ensure you have the following:\n\n- Docker installed\n- Download the [latest release](https://github.com/imrafaelmerino/mighty-meter/releases) of\n  MightyMeter\n- Extract the downloaded file and grant execution permissions for the scripts in the `bin` folder\n- It’s recommended to add the following paths to your shell’s environment `PATH` variable:\n\n```shell\n\nMIGHTY_METER_HOME=\"PATH_TO_HOME\"\n\nchmod -R +x ${MIGHTY_METER_HOME}/bin\n\nexport PATH=\"$MIGHTY_METER_HOME/bin/leader:$MIGHTY_METER_HOME/bin/worker:$PATH\"\n\n```\n\n## \u003ca name=\"leader-install\"\u003e\u003c/a\u003e Installation of the Leader\n\nFor the machine intended as the **Leader** and MightyMeter downloaded, run the following shell\nscript:\n\n```shell\n\nmm.leader.host$ mm-leader-install\n\n```\n\nServices on the Leader will be set up as follows:\n\n- **Nginx** is listening on port 80.\n- **Grafana** is accessible at [http://localhost/grafana](http://localhost/grafana) (set up as a\n  reverse proxy through Nginx, default login is admin/admin).\n- **InfluxDB** is running in a container. Refer to [Querying the Database](#querying-db) for\n  instructions on opening the CLI.\n- **JMeter** leader container is created at the start of a test and removed once the test is\n  complete.\n- In addition to Grafana dashboards, you can view APDEX JMeter reports at\n  http://localhost/jmeter/reports in HTML format and download them as `jtl` files. The JTL format is\n  used by JMeter to store performance test results, typically in CSV files. Each JTL file logs data\n  gathered during a test, including metrics such as response times, status codes, sample names, and\n  other performance indicators.\n\n![GUI](./image/jmeter_report.png)\n\nPort can be customized via the variable `_NGINX_PORT` in the [`.defaults`](bin/.defaults) file.\nComponent versions are specified in the [`.versions`](bin/.versions) file:\n\n```shell\n\n_INFLUXDB_VERSION=2.7.10\n_GRAFANA_VERSION=11.3.0\n_NGINX_VERSION=1.27.2\n_JMETER_VERSION=5.6.3\n_JMETER_OPEN_JDK_VERSION=21-oraclelinux8\n\n```\n\n**You are now ready to use MightyMeter in CLI mode from your local machine!** Check out\n[this example](examples/run-local-cli-mode-testing-example.sh) to get started.\n\n## \u003ca name=\"worker-install\"\u003e\u003c/a\u003e Installation of the Workers\n\nTo set up distributed testing, first install the **Leader** on a designated machine. Next, install\nMightyMeter on each **Worker** machine. For example, on each **Worker** machine with hostnames such\nas **mm.worker.host1**, **mm.worker.host2**, download MightyMeter and execute the following shell\nscript on each Worker:\n\n```shell\nmm.worker.host1$ mm-worker-install --host mm.worker.host1\n```\n\n```shell\nmm.worker.host2$ mm-worker-install --host mm.worker.host2\n```\n\nDon't install the worker nodes on the same machine as the leader—it defeats the purpose. For\nsingle-machine setups, use MightyMeter in local CLI mode instead.\n\n## \u003ca name=\"jmx-config\"\u003e\u003c/a\u003e Configuring Your JMX File\n\nTo persist results in InfluxDB and enable real-time monitoring in Grafana, include the MightyMeter\nlistener in your JMX file, as shown in the jmx file [example.jmx](examples/example.jmx).\n\nHere's how it looks in the JMeter GUI if you open the file:\n\n![GUI](./image/gui-mighty-meter-listener.png)\n\n**You can only modify the following:**\n\n- The `eventTags` variable: set this to your chosen value (it will appear in the `tags` field within\n  the InfluxDB `events` measurement). This value is for informational purposes only.\n- Add custom tags in the format `TAG_name=value`.\n\n## \u003ca name=\"running-tests\"\u003e\u003c/a\u003e Running Tests\n\n### Distributed testing\n\nTo start a distributed test, go to the leader machine and run the shell script `mm-leader-run-tests`\nwith options like:\n\n```shell\n\nmm.leader.host$ mm-leader-run-tests \\\n--duration 3600 \\\n--num-threads 20 \\\n--ramp-up 60 \\\n--leader-host mm.leader.host \\\n--worker-hosts mm.worker.host1,mm.worker.host2 \\\n--env Production \\\n--jmx-file /path/to/jmx-file \\\n--props-file /path/to/props-file \\\n--app My App \\\n--app-version 1.0.0 \\\n--test-name PerformanceTest\n\n```\n\n#### Options:\n\n- **duration**: test duration in seconds.\n- **num-threads**: threads per Worker (total = num-threads \\* Worker count).\n- **ramp-up**: ramp-up time for threads in seconds.\n- **leader-host**: hostname of the Leader.\n- **worker-hosts**: comma-separated Worker hostnames.\n- **env**: test environment (used in InfluxDB and Grafana filters).\n- **app**: application name.\n- **app-version**: tested app version.\n- **jmx-file**: JMeter configuration file (with listener included).\n- **props-file**: additional properties for JMeter.\n\nThis command creates an ephemeral Docker container to start a JMeter client (Leader) and coordinates\nwith active Workers. Monitor tests in real-time on Grafana at `http://localhost/grafana` (default\nlogin: `admin/admin`).\n\n### Local CLI Mode\n\n```shell\n\nlocalhost$ mm-cli-mode-run-tests \\\n--duration 20 \\\n--num-threads 10 \\\n--ramp-up 1 \\\n--env dev \\\n--jmx-file /path/to/jmx-file \\\n--props-file /path/to/props-file \\\n--app myapp \\\n--app-version 1.0.0 \\\n--test-name anotherTest\n\n```\n\n#### Options:\n\n- **duration**: test duration in seconds.\n- **num-threads**: threads per Worker (total = num-threads \\* Worker count).\n- **ramp-up**: ramp-up time for threads in seconds.\n- **env**: test environment (used in InfluxDB and Grafana filters).\n- **app**: application name.\n- **app-version**: tested app version.\n- **jmx-file**: JMeter configuration file (with listener included).\n- **props-file**: additional properties for JMeter.\n\nThis command creates an ephemeral Docker container to start a JMeter that executes the test. Monitor\ntests in real-time on Grafana at `http://localhost/grafana` (default login: `admin/admin`).\n\n## \u003ca name=\"grafana-dashboards\"\u003e\u003c/a\u003e Grafana Dashboards\n\nMightyMeter offers a range of dashboards to visualize both real-time and historical data:\n\n![GUI](./image/grafana_dashboards.png)\n\nHere are a few examples:\n\n- For real-time monitoring:\n\n  ![GUI](./image/grafana_realtime.png)\n\n- To compare two different versions of the same application under identical conditions:\n\n  ![GUI](./image/grafana_compare_versions.png)\n\n- To compare the performance of the same application version under varying user loads:\n\n  ![GUI](./image/grafana_compare_users.png)\n\n## \u003ca name=\"querying-db\"\u003e\u003c/a\u003e Querying the Database\n\nAccess the InfluxDB console on the Leader with `mm-leader-influxdb-console`. Familiarity with\nInfluxDB terms like measurements, series, tags, and fields is helpful. The default database **mm**\ncontains `statistics` and `events`. `events` logs test start/stop times; `statistics` holds\ntransaction metrics.\n\nExample:\n\n```shell\nmm.leader.host$ mm-leader-influxdb-console\n\n\u003e show DATABASES\n\u003e use \"mighty-meter\"\n\u003e select * from events\n\u003e select * from statistics\n\u003e quit\n\n```\n\n## \u003ca name=\"additional-commands\"\u003e\u003c/a\u003e Additional Commands\n\n- **Uninstall MightyMeter**: Run uninstall shell scripts on the Leader and each Worker\n\n  ```shell\n  mm.worker.leader$ mm-leader-uninstall\n  ```\n\n  ```shell\n  mm.worker.host1$ mm-worker-uninstall\n  ```\n\n  ```shell\n  mm.worker.host2$ mm-worker-uninstall\n  ```\n\n- **Access Worker JMeter Logs**:\n\n  ```shell\n  mm.worker.host1$ mm-worker-bash\n  root@container# tail -f /var/log/jmeter/jmeter.log\n  ```\n\n- **Access Leader JMeter Logs**:\n\nGo to http://localhost/jmeter/logs/\n\n- **Stop a running Test**:\n\n  ```shell\n  mm.leader.host$ mm-leader-stop-test\n  ```\n\n---\n\n## \u003ca name=\"generators\"\u003e\u003c/a\u003e Generating Data\n\nGenerating data becomes straightforward and highly efficient with tools like\n[java-fun](https://github.com/imrafaelmerino/java-fun?tab=readme-ov-file#prg) for any data structure\nand [json-values](https://github.com/imrafaelmerino/json-values?tab=readme-ov-file#gen) for JSON.\n\nTo start generating data, simply place the JAR file containing the generators into JMeter's\n[ext-libraries](mighty-jmeter/ext-libraries) folder. For detailed instructions, refer to the\n[java-fun](https://github.com/imrafaelmerino/java-fun?tab=readme-ov-file#jmeter) project readme.\n\nPlease note that the necessary dependencies, _json-values_ and _java-fun_, are already included in\nJMeter's [lib-libraries](mighty-jmeter/lib-libraries) folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrafaelmerino%2Fmighty-meter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimrafaelmerino%2Fmighty-meter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrafaelmerino%2Fmighty-meter/lists"}