Apply suggestions from code review

Co-authored-by: Slavi Pantaleev <slavi@devture.com>

docs/configuring-playbook-synapse-usage-exporter.md

@@ -1,6 +1,15 @@
 # Setting up synapse-usage-exporter (optional)
 
-[synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) Allows you to export the usage statistics of a Synapse homeserver to this container service and be scraped by Prometheus. Synapse does not include usage statistics in its prometheus metrics. They can be reported to a HTTP PUT endpoint 5 minutes after startup and from then on at a fixed interval of once every three hours. This role integrates a simple Flask project that offers a HTTP PUT endpoint and holds the most recent received record available to be scraped py Prometheus.
+[synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) allows you to export the usage statistics of a Synapse homeserver to this container service and for the collected metrics to later be scraped by Prometheus.
+
+Synapse does not include usage statistics in its Prometheus metrics. They can be reported to an HTTP `PUT` endpoint 5 minutes after startup and from then on at a fixed interval of once every three hours. This role integrates a simple [Flask](https://flask.palletsprojects.com) project that offers an HTTP `PUT` endpoint and holds the most recent received record available to be scraped by Prometheus.
+
+Enabling this service will automatically:
+
+- install the synapse-usage-exporter service
+- re-configure Synapse to push (via HTTP `PUT`) usage statistics information to synapse-usage-exporter
+- re-configure [Prometheus](./configuring-playbook-prometheus-grafana.md) (if Grafana is enabled), to periodically scrape metrics from synapse-usage-exporter
+- add a new [Grafana](./configuring-playbook-prometheus-grafana.md) dashboard (if Grafana is enabled) containing Synapse usage statistics
 
 ## Quickstart
 
@@ -9,6 +18,8 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
 ```yaml
 matrix_synapse_usage_exporter_enabled: true
 
-# (optional) Expose endpoint if you want to collect statistics from other homeservers: `matrix.DOMAIN/report-usage-stats/push`
+# (Optional) Expose endpoint if you want to collect statistics from outside (from other homeservers).
+# If enabled, synapse-usage-exporter will be exposed publicly at `matrix.DOMAIN/report-usage-stats/push`.
+# When collecting usage statistics for Synapse running on the same host, you don't need to enable this.
 # matrix_synapse_usage_exporter_proxying_enabled: true
 ```

group_vars/matrix_servers

@@ -4611,7 +4611,7 @@ matrix_synapse_usage_exporter_container_labels_traefik_docker_network: "{{ matri
 matrix_synapse_usage_exporter_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
 matrix_synapse_usage_exporter_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
 
-matrix_synapse_report_stats: "{{ true if matrix_synapse_usage_exporter_enabled else false }}"
+matrix_synapse_report_stats: "{{ matrix_synapse_usage_exporter_enabled }}"
 matrix_synapse_report_stats_endpoint: "http://{{ matrix_synapse_usage_exporter_identifier }}:{{ matrix_synapse_usage_exporter_container_port | string }}/report-usage-stats/push"
 
 ######################################################################

roles/custom/matrix-synapse-usage-exporter/defaults/main.yml

@@ -1,7 +1,7 @@
 ---
 
 # Synapse Usage Exporter
-# Project source code URL: https://github.com/loelkes/synapse-usage-exporter/tree/main
+# Project source code URL: https://github.com/loelkes/synapse-usage-exporter
 
 matrix_synapse_usage_exporter_enabled: false