Added benchmark documentation | refs #32484

README.md

@@ -8,6 +8,7 @@ How to deploy UbiCast products:
 - [Configuration of the controller and inventory](/doc/config.md)
 - [Deployment of UbiCast softwares](/doc/deploy.md)
 - [Build an image](/doc/image.md)
+- [MediaServer Benchmark](/doc/bench.md)
 
 ## Development
 

doc/bench.md

+# Benchmarking
+
+This documentation explains how to benchmark a MediaServer to get the maximum viewers that can be handled.
+The benchmarking tool is based on Locust.
+
+
+## Prerequisite
+
+- Envsetup and ansible [Help to get envsetup](/doc/install.md)
+- An SSH access to the machines that will be used to make requests on MediaServer (you can use the workers for that)
+- A media to test. You can create an empty live stream for the test.
+
+Note that the machines used by the benchmarker must have an access to UbiCast packages (to get the `ubicast-benchmark` package).
+
+
+## Inventory
+
+Create a new inventory with following configuration.
+
+### Hosts file
+
+This file should be located in `<your inventory>/hosts`.
+
+```
+[bench_server]
+worker1.test.com
+
+[bench_worker]
+worker2.test.com
+```
+
+The system targetted with `bench_server` will host the Locust server. This system must be unique.
+
+The systems targetted with `bench_worker` will host the Locust workers. Multiple workers can be used.
+
+
+### Group vars
+
+This file should be located in `<your inventory>/group_vars/all.yml`.
+
+```
+bench_host: <MediaServer URL. Example: "msauto.ubicast.net">
+bench_oid: <Media OID. Example: "l125f58fbb8c655nth76">
+bench_user: <MediaServer account username. Can be empty if the media access is not protected. Example: "test">
+bench_password: <MediaServer account password. Can be empty if the media access is not protected. Example: "pwd">
+bench_host_api_key: <MediaServer master API key>
+```
+
+
+## Install the benchmarker
+
+```
+# ansible-playbook -i inventories/<your inventory> envsetup/playbooks/bench-server.yml
+# ansible-playbook -i inventories/<your inventory> envsetup/playbooks/bench-worker.yml
+```
+
+
+## Start the benchmarker
+
+Disable anti-ddos in MediaServer Nginx configuration (usually in `/etc/nginx/conf.d/limits.conf`).
+
+If the server hosting the bench server is using a firewall, disable it to be able to access the locust interface. For example, if `ferm` is installed: `systemctl ferm stop`.
+
+Go with your browser on `http://<bench_server>:8089`. You might have to use an SSH tunnel to access this port.
+
+Set the number of viewers and the hatch rate (usually the hatch rate is 10% of the viewers count) and start the bench.
+
+Watch for `/var/log/access.log` (warning: this file is buffered by default, you can disable buffer in `nginx.conf`).