From 8fb2719a68ce9260694a8bb97fc9d8683ec55bd0 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 02:31:54 +0900 Subject: [PATCH 1/3] Update docs for Synapse: move descriptions from docs/maintenance-and-troubleshooting.md and create the common section "Troubleshooting" I am not sure what would be the motive to put the instruction for debugging Synapse on maintenance-and-troubleshooting.md above all, but now that we have the common section for an instruction about troubleshooting, it should make sense to move the instruction to the documentation page for configuring Synapse. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse.md | 15 +++++++++++++++ docs/maintenance-and-troubleshooting.md | 16 ---------------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index 12ae0f061..590434117 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -173,3 +173,18 @@ This playbook allows you to enable Synapse metrics, which can provide insight in To enable Synapse runtime metrics see: [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) To enable Synapse usage metrics, see: [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md) + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-synapse`. + +### Increase logging verbosity + +Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. + +If you'd like to debug an issue or [report a Synapse bug](https://github.com/element-hq/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increase the logging verbosity to `INFO`. To do so, add the following configuration to your `vars.yml` file and re-run the playbook: + +```yaml +matrix_synapse_log_level: "INFO" +matrix_synapse_storage_sql_log_level: "INFO" +matrix_synapse_root_log_level: "INFO" diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index 41704dfe4..fa38df727 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -22,22 +22,6 @@ To view systemd-journald logs using [journalctl](https://man.archlinux.org/man/j sudo journalctl -fu matrix-synapse ``` -## Increase logging verbosity - -Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. - -If you'd like to debug an issue or [report a Synapse bug](https://github.com/element-hq/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`. - -Example configuration (`inventory/host_vars/matrix.example.com/vars.yml`): - -```yaml -matrix_synapse_log_level: "INFO" -matrix_synapse_storage_sql_log_level: "INFO" -matrix_synapse_root_log_level: "INFO" -``` - -Re-run the playbook after making these configuration changes. - ## How to check if services work The playbook can perform a check to ensure that you've configured things correctly and that services are running. From b67e5729dacdcdf458815d6849981f1d48b35084 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 02:34:41 +0900 Subject: [PATCH 2/3] Update docs/configuring-playbook-synapse: remove the duplicated anchor link Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index 590434117..f31ca5d81 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -180,7 +180,7 @@ As with all other services, you can find the logs in [systemd-journald](https:// ### Increase logging verbosity -Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. +Because Synapse is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. If you'd like to debug an issue or [report a Synapse bug](https://github.com/element-hq/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increase the logging verbosity to `INFO`. To do so, add the following configuration to your `vars.yml` file and re-run the playbook: From da0952e05862d8a0cb8aba7076fb8ca4ddbfa3b3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 2 Feb 2025 01:12:38 +0900 Subject: [PATCH 3/3] Update docs for Synapse: add anchor links to each other Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse.md | 2 ++ docs/maintenance-synapse.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index f31ca5d81..04e33c36b 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -2,6 +2,8 @@ By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, so that it works for the general case. If that's okay, you can skip this document. +💡 See this page for details about maintaining Synapse: [Synapse maintenance](maintenance-synapse.md) + ## Adjusting the playbook configuration ### Load balancing with workers diff --git a/docs/maintenance-synapse.md b/docs/maintenance-synapse.md index bc78f28fd..cd8f11697 100644 --- a/docs/maintenance-synapse.md +++ b/docs/maintenance-synapse.md @@ -12,6 +12,8 @@ Table of contents: - [Make Synapse faster](#make-synapse-faster) +💡 See this page for details about configuring Synapse: [Configuring Synapse](configuring-playbook-synapse.md) + ## Purging old data with the Purge History API You can use the **[Purge History API](https://github.com/element-hq/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.