Expose synapse-usage-exporter metrics like the metrics of other services

The playbook exposes service metrics under a single endpoint
(`https://matrix.example.com/metrics/*`), controlled by
`matrix_metrics_exposure_enabled` and friends. synapse-usage-exporter was
not wired into this at all, so its metrics could only be scraped by the
integrated Prometheus and were unreachable for an external one.

The role had no metrics router whatsoever. Its only Traefik router (for
the `/report-usage-stats/push` ingestion endpoint) was gated on
`matrix_synapse_usage_exporter_container_labels_traefik_enabled`, which
defaulted to `matrix_synapse_usage_exporter_proxying_enabled`. Adding a
metrics router under that same switch would have meant that exposing
metrics also publishes the ingestion endpoint, so the master switch now
defaults to `true` and each router carries its own conditional.

Despite its generic name, `matrix_synapse_usage_exporter_proxying_enabled`
only ever concerned the endpoint that Synapse pushes usage statistics
**to**, never the metrics endpoint that Prometheus reads **from**. The
documentation now says so explicitly.

Fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/5467

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/configuring-playbook-prometheus-grafana.md

@@ -185,6 +185,7 @@ Name | Description
 `prometheus_nginxlog_exporter_container_labels_metrics_enabled`|Set this to `true` to expose the [prometheus-nginxlog-exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`.
 `ntfy_metrics_listen_http_port`|Set this to a port number (e.g. `9090`) to make [ntfy](configuring-playbook-ntfy.md) serve its metrics (locally, on the container network) on that port.
 `ntfy_container_labels_traefik_metrics_enabled`|Set this to `true` to expose the [ntfy](configuring-playbook-ntfy.md) metrics on `https://matrix.example.com/metrics/ntfy`.
+`matrix_synapse_usage_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [synapse-usage-exporter](configuring-playbook-synapse-usage-exporter.md) metrics on `https://matrix.example.com/metrics/synapse-usage-exporter`.
 
 ### Expose metrics of other services/roles
 

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

@@ -1,7 +1,7 @@
 <!--
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 Michael Hollister
-SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2026 Slavi Pantaleev
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
@@ -38,13 +38,35 @@ To enable synapse-usage-exporter, add the following configuration to your `inven
 ```yaml
 matrix_synapse_usage_exporter_enabled: true
 
-# (Optional) Expose endpoint if you want to collect statistics from outside (from other homeservers).
+# (Optional) Expose the usage-stats ingestion endpoint if you want to collect statistics from outside (from other homeservers).
 # If enabled, synapse-usage-exporter will be exposed publicly at `matrix.example.com/report-usage-stats/push`.
 # When collecting usage statistics for Synapse running on the same host, you don't need to enable this.
 # You can adjust the hostname and path via `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`.
 # matrix_synapse_usage_exporter_proxying_enabled: true
 ```
 
+**Note**: `matrix_synapse_usage_exporter_proxying_enabled` only exposes the endpoint that Synapse pushes usage statistics **to** (`/report-usage-stats/push`). Despite its generic name, it has nothing to do with the metrics endpoint that Prometheus reads **from**. See [below](#collecting-metrics-to-an-external-prometheus-server) for exposing metrics.
+
+### Collecting metrics to an external Prometheus server
+
+Metrics are always served on the container network, so the [integrated Prometheus](./configuring-playbook-prometheus-grafana.md) (`prometheus_enabled: true`) scrapes them without any additional configuration.
+
+To collect them with an **external Prometheus server**, you need to expose them publicly. You can do so by enabling metrics exposure for all services (`matrix_metrics_exposure_enabled: true`), or just for this service:
+
+```yaml
+# Expose the metrics on https://matrix.example.com/metrics/synapse-usage-exporter
+matrix_synapse_usage_exporter_metrics_proxying_enabled: true
+
+# Uncomment to password-protect the metrics for synapse-usage-exporter.
+# matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_enabled: true
+
+# Uncomment and set this part to the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint.
+# See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+# matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_users: ''
+```
+
+Refer to [this section](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) of the Prometheus and Grafana documentation for more details.
+
 ### Adjusting the synapse-usage-exporter URL (optional)
 
 By tweaking the `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.

group_vars/matrix_servers

@@ -5253,6 +5253,13 @@ matrix_synapse_usage_exporter_container_labels_traefik_docker_network: "{{ matri
 matrix_synapse_usage_exporter_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_synapse_usage_exporter_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
 
+matrix_synapse_usage_exporter_metrics_proxying_enabled: "{{ matrix_metrics_exposure_enabled }}"
+matrix_synapse_usage_exporter_metrics_proxying_hostname: "{{ matrix_metrics_exposure_hostname }}"
+matrix_synapse_usage_exporter_metrics_proxying_path: "{{ matrix_metrics_exposure_path_prefix }}/synapse-usage-exporter"
+
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_enabled: "{{ matrix_metrics_exposure_http_basic_auth_enabled }}"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_users: "{{ matrix_metrics_exposure_http_basic_auth_users }}"
+
 ######################################################################
 #
 # /matrix-synapse-usage-exporter

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

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2024 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2024 Michael Hollister
 # SPDX-FileCopyrightText: 2024 Suguru Hirahara
 #
@@ -11,8 +11,11 @@
 
 matrix_synapse_usage_exporter_enabled: false
 
-# Controls the hostname and path that this component exposes its web services on.
+# Controls the hostname and path that the usage-stats ingestion endpoint is exposed on.
 # Only used if `matrix_synapse_usage_exporter_proxying_enabled` is true.
+#
+# The metrics endpoint is exposed separately.
+# See `matrix_synapse_usage_exporter_metrics_proxying_enabled` and friends.
 matrix_synapse_usage_exporter_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_synapse_usage_exporter_path_prefix: /report-usage-stats/push
 
@@ -56,19 +59,34 @@ matrix_synapse_usage_exporter_container_additional_networks: []
 # Extra arguments for the Docker container
 matrix_synapse_usage_exporter_container_extra_arguments: []
 
-# Controls whether the synapse-usage-exporter's web services should be proxied (exposed publicly).
+# Controls whether the synapse-usage-exporter's usage-stats ingestion endpoint should be proxied (exposed publicly).
 #
 # Exposure happens on `matrix.example.com/report-usage-stats/push` by default.
 # See: `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`.
+#
+# This variable does not affect the metrics endpoint in any way.
+# Metrics are always served on the container network (which is enough for a local Prometheus to scrape them)
+# and are exposed publicly via `matrix_synapse_usage_exporter_metrics_proxying_enabled`.
 matrix_synapse_usage_exporter_proxying_enabled: false
 
+# Controls whether synapse-usage-exporter metrics should be proxied (exposed) on `matrix.example.com/metrics/synapse-usage-exporter`.
+#
+# Metrics are always served by the service on the container network, so a local (in-container) Prometheus
+# can scrape them without any of this. Exposing them publicly is only necessary
+# if metrics need to be consumed by another (external) Prometheus server.
+matrix_synapse_usage_exporter_metrics_proxying_enabled: false
+matrix_synapse_usage_exporter_metrics_proxying_hostname: ''
+matrix_synapse_usage_exporter_metrics_proxying_path: /metrics/synapse-usage-exporter
+
 # matrix_synapse_usage_exporter_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
 # See `../templates/labels.j2` for details.
 #
 # To inject your own other container labels, see `matrix_synapse_usage_exporter_container_labels_additional_labels`.
-matrix_synapse_usage_exporter_container_labels_traefik_enabled: "{{ matrix_synapse_usage_exporter_proxying_enabled }}"
+matrix_synapse_usage_exporter_container_labels_traefik_enabled: true
 matrix_synapse_usage_exporter_container_labels_traefik_docker_network: "{{ matrix_synapse_usage_exporter_container_network }}"
 
+# Controls whether labels will be added that expose the usage-stats ingestion endpoint (see `matrix_synapse_usage_exporter_proxying_enabled`)
+matrix_synapse_usage_exporter_container_labels_traefik_usage_stats_enabled: "{{ matrix_synapse_usage_exporter_proxying_enabled }}"
 matrix_synapse_usage_exporter_container_labels_traefik_path_prefix: "{{ matrix_synapse_usage_exporter_path_prefix }}"
 matrix_synapse_usage_exporter_container_labels_traefik_rule: "Host(`{{ matrix_synapse_usage_exporter_hostname }}`) && PathPrefix(`{{ matrix_synapse_usage_exporter_container_labels_traefik_path_prefix }}`)"
 matrix_synapse_usage_exporter_container_labels_traefik_priority: 0
@@ -76,6 +94,19 @@ matrix_synapse_usage_exporter_container_labels_traefik_entrypoints: "web-secure"
 matrix_synapse_usage_exporter_container_labels_traefik_tls: "{{ matrix_synapse_usage_exporter_container_labels_traefik_entrypoints != 'web' }}"
 matrix_synapse_usage_exporter_container_labels_traefik_tls_certResolver: default  # noqa var-naming
 
+# Controls whether labels will be added that expose the metrics endpoint (see `matrix_synapse_usage_exporter_metrics_proxying_enabled`)
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_enabled: "{{ matrix_synapse_usage_exporter_metrics_proxying_enabled }}"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_path: "{{ matrix_synapse_usage_exporter_metrics_proxying_path }}"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_rule: "Host(`{{ matrix_synapse_usage_exporter_metrics_proxying_hostname }}`) && Path(`{{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_path }}`)"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_priority: 0
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_entrypoints: "{{ matrix_synapse_usage_exporter_container_labels_traefik_entrypoints }}"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_tls: "{{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_entrypoints != 'web' }}"
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_tls_certResolver: "{{ matrix_synapse_usage_exporter_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_enabled: false
+# See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_users: ''
+
 # matrix_synapse_usage_exporter_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
 # See `../templates/labels.j2` for details.
 #

roles/custom/matrix-synapse-usage-exporter/tasks/validate_config.yml

@@ -1,10 +1,19 @@
-# SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2025 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2025 Suguru Hirahara
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 ---
 
+- name: Fail if required matrix-synapse-usage-exporter settings not defined
+  ansible.builtin.fail:
+    msg: >
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
+  with_items:
+    - {'name': 'matrix_synapse_usage_exporter_metrics_proxying_hostname', when: "{{ matrix_synapse_usage_exporter_metrics_proxying_enabled }}"}
+    - {'name': 'matrix_synapse_usage_exporter_metrics_proxying_path', when: "{{ matrix_synapse_usage_exporter_metrics_proxying_enabled }}"}
+
 - name: (Deprecation) Catch and report renamed matrix-synapse-usage-exporter settings
   ansible.builtin.fail:
     msg: >-

roles/custom/matrix-synapse-usage-exporter/templates/labels.j2

@@ -1,5 +1,6 @@
 {#
 SPDX-FileCopyrightText: 2024 Michael Hollister
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -13,6 +14,7 @@ traefik.docker.network={{ matrix_synapse_usage_exporter_container_labels_traefik
 
 traefik.http.services.matrix-synapse-usage-exporter.loadbalancer.server.port={{ matrix_synapse_usage_exporter_container_port }}
 
+{% if matrix_synapse_usage_exporter_container_labels_traefik_usage_stats_enabled %}
 ############################################################
 #                                                          #
 # Report Usage Stats (/report-usage-stats/push)            #
@@ -38,6 +40,46 @@ traefik.http.routers.matrix-synapse-usage-exporter.tls.certResolver={{ matrix_sy
 # /Report Usage Stats (/report-usage-stats/push)           #
 #                                                          #
 ############################################################
+{% endif %}
+
+{% if matrix_synapse_usage_exporter_container_labels_traefik_metrics_enabled %}
+############################################################
+#                                                          #
+# Metrics                                                  #
+#                                                          #
+############################################################
+
+{% set metricsMiddlewares = [] %}
+
+{% if matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_enabled %}
+{% set metricsMiddlewares = metricsMiddlewares + ['matrix-synapse-usage-exporter-metrics-basic-auth'] %}
+traefik.http.middlewares.matrix-synapse-usage-exporter-metrics-basic-auth.basicauth.users={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_users }}
+{% endif %}
+
+{% set metricsMiddlewares = metricsMiddlewares + ['matrix-synapse-usage-exporter-metrics-replace-path'] %}
+traefik.http.middlewares.matrix-synapse-usage-exporter-metrics-replace-path.replacepath.path=/metrics
+
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.rule={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_rule }}
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.middlewares={{ metricsMiddlewares | join(',') }}
+
+{% if matrix_synapse_usage_exporter_container_labels_traefik_metrics_priority | int > 0 %}
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.priority={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.service=matrix-synapse-usage-exporter
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.entrypoints={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_entrypoints }}
+
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.tls={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_tls | to_json }}
+{% if matrix_synapse_usage_exporter_container_labels_traefik_metrics_tls %}
+traefik.http.routers.matrix-synapse-usage-exporter-metrics.tls.certResolver={{ matrix_synapse_usage_exporter_container_labels_traefik_metrics_tls_certResolver }}
+{% endif %}
+
+############################################################
+#                                                          #
+# /Metrics                                                 #
+#                                                          #
+############################################################
+{% endif %}
 
 {% endif %}