site: fill out clustered_job_runner_management section

site/src/SUMMARY.md

@@ -16,4 +16,8 @@
         - [Layers](./cargo_maelstrom/layers.md)
         - [Container Images](./cargo_maelstrom/container_images.md)
 - [Clustered Job Runner Management](./clustered_job_runner_management.md)
+    - [Broker Configuration](./clustered_job_runner_management/broker.md)
+    - [Worker Configuration](./clustered_job_runner_management/worker.md)
+    - [Web UI](./clustered_job_runner_management/web_ui.md)
     - [Job States](./clustered_job_runner_management/job_states.md)
+    - [Log Level](./clustered_job_runner_management/log_level.md)

site/src/cargo_maelstrom/configuration.md

@@ -6,15 +6,34 @@ tests are run.
 
 ## Configuring `cargo-maelstrom`
 
+`cargo-maelstrom` can be configured with the CLI, environment variables, or a
+configuration file.
+
 The default configuration file path is
 `<workspace-root>/.config/cargo-maelstrom.toml`. This path can be overridden by
 passing the `--config-file` option via the CLI.
 
-It can contain the following options
-- `broker`: the address of the broker to connect to
+Here are the different options
+
+- [`broker`](#the-broker-field): the address of the broker to connect to
 - `[run]`: contains options about the `run` sub-command
-    - `quiet`: if true, use quiet mode by default
-    (See [Running Tests >> Terminal Output](./running_tests.html#terminal-output))
+    - [`quiet`](#the-quiet-field): if true, use quiet mode
+
+## The `broker` Field
+- TOML: `broker = "1.2.3.4:9000"`
+- CLI: `--broker 1.2.3.4:9000`
+- ENV: `CARGO_MAELSTROM_BROKER=1.2.3.4:9000`
+
+This is the network address of the broker which the client will attempt to
+establish a connection to.
+
+## The `quiet` Field
+- TOML: `quiet = true`
+- CLI: `--quiet`
+- ENV: `CARGO_MAELSTROM_RUN="{ quiet = true }"`
+
+Enables quiet mode. See
+[Running Tests >> Terminal Output](./running_tests.html#terminal-output).
 
 ## Configuring Tests
 

site/src/clustered_job_runner_management.md

@@ -1 +1,10 @@
 # Clustered Job Runner Management
+
+Both the broker and the worker can be configured using either the command line
+or via a configuration file. See their specific pages for more information
+- [Broker Management](./clustered_job_runner_management/broker.md)
+- [Worker Management](./clustered_job_runner_management/worker.md)
+
+The broker can be monitored using the
+[web UI](./clustered_job_runnner_management/web_ui.md). It runs an HTTP server on
+the configured HTTP port.

site/src/clustered_job_runner_management/broker.md

@@ -0,0 +1,54 @@
+# Broker Management
+
+The broker can be configured via CLI, configuration file, or environment
+variables. CLI or environment variables override configuration file values.
+
+Configuration default path is
+`<working-directory/.config/maelstrom-broker.toml`. This can be overridden with
+the `--config-file` CLI argument.
+
+Here are the different options
+
+- [`port`](#the-port-field) main port to listen on
+- [`http_port`](#the-http_port-field) web UI port to listen on
+- [`cache_root`](#the-cache_root-field) location of cache
+- [`cache_bytes_used_target`](#the-cache_bytes_used_target-field) target amount
+    of disk space used for cache
+- [`log_level`](#the-log_level-field) minimum log level to output
+
+## The `port` Field
+- TOML: `port = 9000`
+- CLI: `--port 9000`
+- ENV: `MAELSTROM_BROKER_PORT=9000`
+
+This is the port the broker listens on for client and worker connections.
+
+## The `http_port` Field
+- TOML: `http_port = 9001`
+- CLI: `--http-port 9001`
+- ENV: `MAELSTROM_BROKER_HTTP_PORT=9001`
+
+This is the port the broker listens on for HTTP connections in order to serve
+the web UI.
+
+## The `cache_root` Field
+- TOML: `cache_root = "/home/maelstrom-broker/cache"`
+- CLI: `--cache-root /home/maelstrom-broker/cache`
+- ENV: `MAELSTROM_BROKER_CACHE_ROOT=/home/maelstrom-broker/cache`
+
+This is the path on the local file-system where the broker will store its cache.
+
+## The `cache_bytes_used_target` Field
+- TOML: `cache_bytes_used_target = 1048576`
+- CLI: `--cache-bytes-used-target 1048576`
+- ENV: `MAELSTROM_BROKER_CACHE_BYTES_USED_TARGET=1048576`
+
+This is the target number of bytes for the cache. This bound isn't followed
+strictly, so it's best to be conservative.
+
+## The `log_level` Field
+- TOML: `log_level = "error"`
+- CLI: `--log-level error`
+- ENV: `MAELSTROM_BROKER_LOG_LEVEL=error`
+
+This controls the [Log Level](./log_level.md) for the broker

site/src/clustered_job_runner_management/log_level.md

@@ -0,0 +1,13 @@
+# Log Level
+The broker and the worker output log messages. Each message is tagged with log
+level. The log level is an ordered listing of named tags. Each subsequent tag has
+a decreasing level of severity. The following is an ordered listing of the log
+levels (ordered from high to low severity)
+
+- `"error"`: these messages indicate some severe problem
+- `"warning"`: these messages indicate a not so severe problem
+- `"info"`: these messages are purely informational
+- `"debug"`: these messages are mostly for developers
+
+A program will only display messages tagged with equal or higher severity level
+to the currently set log level.

site/src/clustered_job_runner_management/web_ui.md

@@ -0,0 +1,23 @@
+# Web UI
+
+The broker has a web UI that is available by connecting via the configured HTTP
+port. See [Broker Configuration > http_port](./broker.md#the-http_port-field).
+
+The following is an explanation of the various elements on the web UI.
+
+## Connected Machines
+The web UI contains information about the number of client and the number of
+worker connected to the broker. Keep in mind, the web UI itself is counted as a
+client.
+
+## Used Slots
+A slot is the ability to run a job on a worker. The more workers connected, the
+more number of slots. See
+[Worker Configuration > Slots](./worker.md#the-slots-field).
+
+## Job Statistics
+The web UI also contains information about current and past jobs. This includes
+the current number of jobs, and graphs containing historical information about
+jobs and their states. There is a graph per connected client, and there is an
+aggregate graph at the top. The graphs are all stacked line-charts. See [Job
+States](./job_states.md) for information about what the various states mean.

site/src/clustered_job_runner_management/worker.md

@@ -0,0 +1,58 @@
+# Worker Management
+
+The worker can be configured via CLI, configuration file, or environment
+variables. CLI or environment variables override configuration file values.
+
+Configuration default path is
+`<working-directory/.config/maelstrom-worker.toml`. This can be overridden with
+the `--config-file` CLI argument.
+
+Here are the different options
+
+- [`broker`](#the-broker-field) the address of the broker
+- [`slots`](#the-slots-field) number of slots to allocate
+- [`cache_root`](#the-cache_root-field) location of cache
+- [`cache_bytes_used_target`](#the-cache_bytes_used_target-field) target amount
+    of disk space used for cache
+- [`inline_limit`](#the-inline_limit-field) maximum size of inline captured job
+    output
+- [`log_level`](#the-log_level-field) minimum log level to output
+
+## The `broker` Field
+- TOML: `broker = "1.2.3.4:9000"`
+- CLI: `--broker 1.2.3.4:9000`
+- ENV: `MAELSTROM_WORKER_BROKER=1.2.3.4:9000`
+
+This is the network address of the broker which the worker will attempt to
+establish a connection to.
+
+## The `slots` Field
+- TOML: `slots = 24`
+- CLI: `--slots 24`
+- ENV: `MAELSTROM_WORKER_SLOTS=24`
+
+This is the number of slots to allocate for this worker. The slots are the
+maximum number of concurrent jobs allowed. This is the effective job parallelism
+for this worker.
+
+## The `cache_root` Field
+- TOML: `cache_root = "/home/maelstrom-worker/cache"`
+- CLI: `--cache-root /home/maelstrom-worker/cache`
+- ENV: `MAELSTROM_WORKER_CACHE_ROOT=/home/maelstrom-worker/cache`
+
+This is the path on the local file-system where the worker will store its cache.
+
+## The `cache_bytes_used_target` Field
+- TOML: `cache_bytes_used_target = 1048576`
+- CLI: `--cache-bytes-used-target 1048576`
+- ENV: `MAELSTROM_WORKER_CACHE_BYTES_USED_TARGET=1048576`
+
+This is the target number of bytes for the cache. This bound isn't followed
+strictly, so it's best to be conservative.
+
+## The `log_level` Field
+- TOML: `log_level = "error"`
+- CLI: `--log-level error`
+- ENV: `MAELSTROM_BROKER_LOG_LEVEL=error`
+
+This controls the [Log Level](./log_level.md) for the worker

site/src/install/clustered_job_runner.md

@@ -76,8 +76,13 @@ command-line arguments. The HTTP port has a web interface we can use to monitor
 and interact with the broker. The other port is the port workers and clients
 will connect to.
 
-It stores its caches in `<working-directory>/.cache/maelstrom-broker`. For the
-given set-up this should be `/home/maelstrom-broker/.cache/maelstrom-broker`
+The broker can be configured using CLI, environment variables, or configuration
+file, for more information see [Broker
+Configuration](./clustered_job_runner_management/broker.md)
+
+By default it stores its caches in
+`<working-directory>/.cache/maelstrom-broker`. For the given set-up this should
+be `/home/maelstrom-broker/.cache/maelstrom-broker`
 
 ## Installing the Worker
 
@@ -138,7 +143,12 @@ sudo systemctl start maelstrom-worker
 The worker should be running now. To make sure you can pull up the broker web UI
 and it should now show that there is 1 worker.
 
-It stores its caches in `<working-directory>/.cache/maelstrom-worker`. For the
-given set-up this should be `/home/maelstrom-worker/.cache/maelstrom-worker`
+The worker can be configured using CLI, environment variables, or configuration
+file, for more information see [Worker
+Configuration](./clustered_job_runner_management/worker.md)
+
+By default it stores its caches in
+`<working-directory>/.cache/maelstrom-worker`. For the given set-up this should
+be `/home/maelstrom-worker/.cache/maelstrom-worker`
 
 Repeat these steps for every machine you wish to install a worker on to.