diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index 3b022a987..16e41f958 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/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 diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index cb66cdffe..8be14c11e 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -1,7 +1,7 @@ @@ -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. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 0dc99ef78..216244f16 100755 --- a/group_vars/matrix_servers +++ b/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 diff --git a/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml b/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml index daa0161e7..030581bc9 100644 --- a/roles/custom/matrix-synapse-usage-exporter/defaults/main.yml +++ b/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. # diff --git a/roles/custom/matrix-synapse-usage-exporter/tasks/validate_config.yml b/roles/custom/matrix-synapse-usage-exporter/tasks/validate_config.yml index 8238b2401..a1e184ac3 100644 --- a/roles/custom/matrix-synapse-usage-exporter/tasks/validate_config.yml +++ b/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: >- diff --git a/roles/custom/matrix-synapse-usage-exporter/templates/labels.j2 b/roles/custom/matrix-synapse-usage-exporter/templates/labels.j2 index 50c3ca82f..a50ad0923 100755 --- a/roles/custom/matrix-synapse-usage-exporter/templates/labels.j2 +++ b/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 %}