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>

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 %}