From 3c0abc673b89c5473a0fd9726d532781c3c7cdb4 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 6 Oct 2022 17:14:21 +0200
Subject: [PATCH 01/25] Add workers settings to configuration manual

---
 .../configuration/config_documentation.md     | 143 ++++++++++++++++--
 docs/workers.md                               |  14 +-
 2 files changed, 138 insertions(+), 19 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 8a71a934ea2a..97f26d43c6c7 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -1338,7 +1338,8 @@ Config options related to logging.
 ---
 ### `log_config`
 
-This option specifies a yaml python logging config file as described [here](https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema).
+This option specifies a yaml python logging config file as described
+[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
 
 Example configuration:
 ```yaml
@@ -3673,11 +3674,137 @@ opentracing:
 ## Workers ##
 Configuration options related to workers.
 
+Please also note the [further documentation for workers](../../workers.md).
+
+---
+### `worker_app`
+
+The type of worker. The currently available worker applications are listed
+in [worker documentation](../../workers.md#available-worker-applications).
+
+The most common worker is the `synapse.app.generic_worker`.
+
+Example configuration:
+```yaml
+worker_app: synapse.app.generic_worker
+```
+---
+### `worker_name`
+
+A unique name for the worker. The worker needs a name to be addressed in
+further parameters and identification in log files.
+
+Example configuration:
+```yaml
+worker_name: generic_worker1
+```
+---
+### `worker_replication_host`
+
+The HTTP replication endpoint that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](#listeners).
+
+Example configuration:
+```yaml
+worker_replication_host: 127.0.0.1
+```
+---
+### `worker_replication_http_port`
+
+The HTTP replication port that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](#listeners).
+
+Example configuration:
+```yaml
+worker_replication_http_port: 9093
+```
+---
+### `worker_replication_secret`
+
+A shared secret used by the replication APIs to authenticate HTTP requests
+from workers.
+
+By default this is unused and traffic is not authenticated.
+
+Example configuration:
+```yaml
+worker_replication_secret: "secret_secret"
+```
+---
+### `worker_listeners`
+
+A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
+option with an http listener, in the same way as the [`listeners` option](#listeners)
+in the shared config.
+
+Example configuration:
+```yaml
+worker_listeners:
+  - type: http
+    port: 8083
+    resources:
+      - names: [client, federation]
+```
+---
+### `worker_daemonize`
+
+Specifies whether the worker should be daemonize. If [systemd](../../systemd-with-workers/README.md)
+is used, this must not configured. Systemd manages daemonization itself. Defaults to `false`.
+
+Example configuration:
+```yaml
+worker_daemonize: true
+```
+---
+### `worker_pid_file`
+
+When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
+This is the same way as the [`pid_file` option](#pid_file) in the shared config.
+
+Example configuration:
+```yaml
+worker_pid_file: DATADIR/generic_worker1.pid
+```
+---
+### `worker_log_config`
+
+This option specifies a yaml python logging config file as described
+[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
+This is the same way as the [`log_config` option](#log_config) in the shared config.
+
+Example configuration:
+```yaml
+worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
+```
+---
+### `start_pushers`
+
+Controls sending of push notifications on the main process. Set to `false`
+if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.
+
+Example configuration:
+```yaml
+start_pushers: false
+```
+---
+### `pusher_instances`
+
+It is possible to run multiple pusher workers, in which case the
+work is balanced across them. Use this setting to list the pushers by [`worker_name`](#worker_name).
+
+Example configuration:
+```yaml
+pusher_instances:
+  - pusher_worker1
+```
 ---
 ### `send_federation`
 
 Controls sending of outbound federation transactions on the main process.
-Set to false if using a federation sender worker. Defaults to true.
+Set to false if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
+Defaults to `true`.
 
 Example configuration:
 ```yaml
@@ -3736,17 +3863,6 @@ Example configuration:
 run_background_tasks_on: worker1
 ```
 ---
-### `worker_replication_secret`
-
-A shared secret used by the replication APIs to authenticate HTTP requests
-from workers.
-
-By default this is unused and traffic is not authenticated.
-
-Example configuration:
-```yaml
-worker_replication_secret: "secret_secret"
-```
 ### `redis`
 
 Configuration for Redis when using workers. This *must* be enabled when
@@ -3765,6 +3881,7 @@ redis:
   port: 6379
   password: <secret_password>
 ```
+---
 ## Background Updates ##
 Configuration settings related to background updates.
 
diff --git a/docs/workers.md b/docs/workers.md
index 25f2e13237f8..d0ded0e3f73f 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -123,13 +123,15 @@ public internet; replication traffic is:
 ### Worker configuration
 
 In the config file for each worker, you must specify:
- * The type of worker (`worker_app`). The currently available worker applications are listed below.
- * A unique name for the worker (`worker_name`).
+ * The type of worker ([`worker_app`](usage/configuration/config_documentation.md#worker_app)).
+   The currently available worker applications are listed below.
+ * A unique name for the worker ([`worker_name`](usage/configuration/config_documentation.md#worker_name)).
  * The HTTP replication endpoint that it should talk to on the main synapse process
-   (`worker_replication_host` and `worker_replication_http_port`)
- * If handling HTTP requests, a `worker_listeners` option with an `http`
-   listener, in the same way as the [`listeners`](usage/configuration/config_documentation.md#listeners)
-   option in the shared config.
+   ([`worker_replication_host`](usage/configuration/config_documentation.md#worker_replication_host) and
+   [`worker_replication_http_port`](usage/configuration/config_documentation.md#worker_replication_http_port))
+ * If handling HTTP requests, a [`worker_listeners`](usage/configuration/config_documentation.md#worker_listeners)
+   option with an `http` listener, in the same way as the
+   [`listeners`](usage/configuration/config_documentation.md#listeners) option in the shared config.
  * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for
    the main process (`worker_main_http_uri`).
 

From 167b28eeed5780295b9061678bf615ba0d51d0c5 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 6 Oct 2022 17:19:08 +0200
Subject: [PATCH 02/25] newsfile

---
 changelog.d/14086.doc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/14086.doc

diff --git a/changelog.d/14086.doc b/changelog.d/14086.doc
new file mode 100644
index 000000000000..de0e1715d6e3
--- /dev/null
+++ b/changelog.d/14086.doc
@@ -0,0 +1 @@
+Add workers settings to [configuration manual](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#workers).

From 895fa0d19861d9103d3a98c797f79dd991316a39 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Sat, 8 Oct 2022 09:37:18 +0200
Subject: [PATCH 03/25] Update `pusher_instances`

---
 docs/usage/configuration/config_documentation.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 7b94fcd15661..f0c2dd483969 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3791,13 +3791,16 @@ start_pushers: false
 ---
 ### `pusher_instances`
 
-It is possible to run multiple pusher workers, in which case the
+It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher), in which case the
 work is balanced across them. Use this setting to list the pushers by [`worker_name`](#worker_name).
 
+If only one pusher worker is configured, this setting is not necessary.
+
 Example configuration:
 ```yaml
 pusher_instances:
   - pusher_worker1
+  - pusher_worker2
 ```
 ---
 ### `send_federation`
@@ -3855,8 +3858,9 @@ stream_writers:
 ---
 ### `run_background_tasks_on`
 
-The worker that is used to run background tasks (e.g. cleaning up expired
-data). If not provided this defaults to the main process.
+The [worker](../../workers.md#background-tasks) that is used to run
+background tasks (e.g. cleaning up expired data). If not provided this
+defaults to the main process.
 
 Example configuration:
 ```yaml

From 2c0652dafc04291bf08cf5a22f825c73bd73005b Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 13 Oct 2022 17:10:08 +0200
Subject: [PATCH 04/25] Move from `config_documentation.md` to `workers.md`

---
 .../configuration/config_documentation.md     | 113 +++--------------
 docs/workers.md                               | 119 ++++++++++++++++--
 2 files changed, 121 insertions(+), 111 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index eb383111e079..3db62362eb7e 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -159,7 +159,7 @@ including _matrix/...). This is the same URL a user might enter into the
 'Custom Homeserver URL' field on their client. If you use Synapse with a
 reverse proxy, this should be the URL to reach Synapse via the proxy.
 Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
-'listeners' below).
+['listeners'](#listeners) below).
 
 Defaults to `https://<server_name>/`.
 
@@ -3673,55 +3673,14 @@ opentracing:
 ---
 ## Workers ##
 Configuration options related to workers.
+Workers are used to scale horizontally and distribute the load to different processes.
 
-Please also note the [further documentation for workers](../../workers.md).
+These switches are all for the shared configuration to give the main process
+the necessary information. The configuration of the workers is described
+in detail in the [worker documentation](../../workers.md).
 
 ---
-### `worker_app`
-
-The type of worker. The currently available worker applications are listed
-in [worker documentation](../../workers.md#available-worker-applications).
-
-The most common worker is the `synapse.app.generic_worker`.
-
-Example configuration:
-```yaml
-worker_app: synapse.app.generic_worker
-```
----
-### `worker_name`
-
-A unique name for the worker. The worker needs a name to be addressed in
-further parameters and identification in log files.
-
-Example configuration:
-```yaml
-worker_name: generic_worker1
-```
----
-### `worker_replication_host`
-
-The HTTP replication endpoint that it should talk to on the main Synapse process.
-The main Synapse process defines this with a `replication` resource in
-[`listeners` option](#listeners).
-
-Example configuration:
-```yaml
-worker_replication_host: 127.0.0.1
-```
----
-### `worker_replication_http_port`
-
-The HTTP replication port that it should talk to on the main Synapse process.
-The main Synapse process defines this with a `replication` resource in
-[`listeners` option](#listeners).
-
-Example configuration:
-```yaml
-worker_replication_http_port: 9093
-```
----
-### `worker_replication_secret`
+#### `worker_replication_secret`
 
 A shared secret used by the replication APIs to authenticate HTTP requests
 from workers.
@@ -3733,52 +3692,6 @@ Example configuration:
 worker_replication_secret: "secret_secret"
 ```
 ---
-### `worker_listeners`
-
-A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
-option with an http listener, in the same way as the [`listeners` option](#listeners)
-in the shared config.
-
-Example configuration:
-```yaml
-worker_listeners:
-  - type: http
-    port: 8083
-    resources:
-      - names: [client, federation]
-```
----
-### `worker_daemonize`
-
-Specifies whether the worker should be daemonize. If [systemd](../../systemd-with-workers/README.md)
-is used, this must not configured. Systemd manages daemonization itself. Defaults to `false`.
-
-Example configuration:
-```yaml
-worker_daemonize: true
-```
----
-### `worker_pid_file`
-
-When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
-This is the same way as the [`pid_file` option](#pid_file) in the shared config.
-
-Example configuration:
-```yaml
-worker_pid_file: DATADIR/generic_worker1.pid
-```
----
-### `worker_log_config`
-
-This option specifies a yaml python logging config file as described
-[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
-This is the same way as the [`log_config` option](#log_config) in the shared config.
-
-Example configuration:
-```yaml
-worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
-```
----
 ### `start_pushers`
 
 Controls sending of push notifications on the main process. Set to `false`
@@ -3791,8 +3704,9 @@ start_pushers: false
 ---
 ### `pusher_instances`
 
-It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher), in which case the
-work is balanced across them. Use this setting to list the pushers by [`worker_name`](#worker_name).
+It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
+in which case the work is balanced across them. Use this setting to list the pushers by
+[`worker_name`](../../workers.md#worker_name).
 
 If only one pusher worker is configured, this setting is not necessary.
 
@@ -3816,8 +3730,9 @@ send_federation: false
 ---
 ### `federation_sender_instances`
 
-It is possible to run multiple federation sender workers, in which case the
-work is balanced across them. Use this setting to list the senders.
+It is possible to run multiple
+[federation sender worker](../../workers.md#synapseappfederation_sender), in which
+case the work is balanced across them. Use this setting to list the senders.
 
 This configuration setting must be shared between all federation sender workers, and if
 changed all federation sender workers must be stopped at the same time and then
@@ -3834,6 +3749,7 @@ federation_sender_instances:
 
 When using workers this should be a map from worker name to the
 HTTP replication listener of the worker, if configured.
+Not every type of worker needs a HTTP replications listener.
 
 Example configuration:
 ```yaml
@@ -3869,8 +3785,7 @@ run_background_tasks_on: worker1
 ---
 ### `redis`
 
-Configuration for Redis when using workers. This *must* be enabled when
-using workers (unless using old style direct TCP configuration).
+Configuration for Redis when using workers. This *must* be enabled when using workers.
 This setting has the following sub-options:
 * `enabled`: whether to use Redis support. Defaults to false.
 * `host` and `port`: Optional host and port to use to connect to redis. Defaults to
diff --git a/docs/workers.md b/docs/workers.md
index 5d4435f3117f..f840c6f88148 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -88,9 +88,11 @@ shared configuration file.
 ### Shared configuration
 
 Normally, only a couple of changes are needed to make an existing configuration
-file suitable for use with workers. First, you need to enable an "HTTP replication
-listener" for the main process; and secondly, you need to enable redis-based
-replication. Optionally, a shared secret can be used to authenticate HTTP
+file suitable for use with workers. First, you need to enable an
+["HTTP replication listener"](usage/configuration/config_documentation.html#listeners)
+for the main process; and secondly, you need to enable
+[redis-based replication](usage/configuration/config_documentation.html#redis).
+Optionally, a shared secret can be used to authenticate HTTP
 traffic between workers. For example:
 
 ```yaml
@@ -111,7 +113,8 @@ redis:
     enabled: true
 ```
 
-See the [configuration manual](usage/configuration/config_documentation.html) for the full documentation of each option.
+See the [configuration manual](usage/configuration/config_documentation.html)
+for the full documentation of each option.
 
 Under **no circumstances** should the replication listener be exposed to the
 public internet; replication traffic is:
@@ -123,15 +126,14 @@ public internet; replication traffic is:
 ### Worker configuration
 
 In the config file for each worker, you must specify:
- * The type of worker ([`worker_app`](usage/configuration/config_documentation.md#worker_app)).
-   The currently available worker applications are listed below.
- * A unique name for the worker ([`worker_name`](usage/configuration/config_documentation.md#worker_name)).
+ * The type of worker ([`worker_app`](#worker_app)).
+   The currently available worker applications are listed [below](#available-worker-applications).
+ * A unique name for the worker ([`worker_name`](#worker_name)).
  * The HTTP replication endpoint that it should talk to on the main synapse process
-   ([`worker_replication_host`](usage/configuration/config_documentation.md#worker_replication_host) and
-   [`worker_replication_http_port`](usage/configuration/config_documentation.md#worker_replication_http_port))
- * If handling HTTP requests, a [`worker_listeners`](usage/configuration/config_documentation.md#worker_listeners)
-   option with an `http` listener, in the same way as the
-   [`listeners`](usage/configuration/config_documentation.md#listeners) option in the shared config.
+   ([`worker_replication_host`](#worker_replication_host) and
+   [`worker_replication_http_port`](#worker_replication_http_port)).
+ * If handling HTTP requests, a [`worker_listeners`](#worker_listeners) option
+   with an `http` listener.
  * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for
    the main process (`worker_main_http_uri`).
 
@@ -148,6 +150,99 @@ plain HTTP endpoint on port 8083 separately serving various endpoints, e.g.
 Obviously you should configure your reverse-proxy to route the relevant
 endpoints to the worker (`localhost:8083` in the above example).
 
+---
+#### `worker_app`
+
+The type of worker. The currently available worker applications are listed
+[below](#available-worker-applications).
+
+The most common worker is the `synapse.app.generic_worker`.
+
+Example configuration:
+```yaml
+worker_app: synapse.app.generic_worker
+```
+---
+#### `worker_name`
+
+A unique name for the worker. The worker needs a name to be addressed in
+further parameters and identification in log files.
+
+Example configuration:
+```yaml
+worker_name: generic_worker1
+```
+---
+#### `worker_replication_host`
+
+The HTTP replication endpoint that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](#listeners).
+
+Example configuration:
+```yaml
+worker_replication_host: 127.0.0.1
+```
+---
+#### `worker_replication_http_port`
+
+The HTTP replication port that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](usage/configuration/config_documentation.html#listeners).
+
+Example configuration:
+```yaml
+worker_replication_http_port: 9093
+```
+---
+#### `worker_listeners`
+
+A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
+option with an http listener, in the same way as the
+[`listeners` option](usage/configuration/config_documentation.html#listeners)
+in the shared config.
+
+Example configuration:
+```yaml
+worker_listeners:
+  - type: http
+    port: 8083
+    resources:
+      - names: [client, federation]
+```
+---
+#### `worker_daemonize`
+
+Specifies whether the worker should be daemonize. If [systemd](systemd-with-workers/README.md)
+is used, this must not configured. Systemd manages daemonization itself. Defaults to `false`.
+
+Example configuration:
+```yaml
+worker_daemonize: true
+```
+---
+#### `worker_pid_file`
+
+When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
+This is the same way as the[`pid_file` option](usage/configuration/config_documentation.html#pid_file)
+in the shared config.
+
+Example configuration:
+```yaml
+worker_pid_file: DATADIR/generic_worker1.pid
+```
+---
+#### `worker_log_config`
+
+This option specifies a yaml python logging config file as described
+[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
+This is the same way as the [`log_config` option](usage/configuration/config_documentation.html#log_config)
+in the shared config.
+
+Example configuration:
+```yaml
+worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
+```
 
 ### Running Synapse with workers
 

From 3b144efdff3bb908cec485319b35568ce65560b5 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Mon, 24 Oct 2022 17:10:34 +0200
Subject: [PATCH 05/25] Move docs back to `config_documentation.md`

---
 docs/sample_log_config.yaml                   |   2 +-
 .../configuration/config_documentation.md     | 134 ++++++++++++--
 docs/workers.md                               | 170 +++++-------------
 synapse/config/logger.py                      |   2 +-
 4 files changed, 171 insertions(+), 137 deletions(-)

diff --git a/docs/sample_log_config.yaml b/docs/sample_log_config.yaml
index 3065a0e2d986..df18726f5506 100644
--- a/docs/sample_log_config.yaml
+++ b/docs/sample_log_config.yaml
@@ -6,7 +6,7 @@
 # Synapse also supports structured logging for machine readable logs which can
 # be ingested by ELK stacks. See [2] for details.
 #
-# [1]: https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
+# [1]: https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema
 # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
 
 version: 1
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index ab26ad0f21a5..420c682fb792 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -1767,7 +1767,7 @@ url_preview_ip_range_blacklist:
   - 'ff00::/8'
   - 'fec0::/10'
 ```
-----
+---
 ### `url_preview_ip_range_whitelist`
 
 This option sets a list of IP address CIDR ranges that the URL preview spider is allowed
@@ -1861,7 +1861,7 @@ Example configuration:
    - 'fr;q=0.8'
    - '*;q=0.7'
 ```
-----
+---
 ### `oembed`
 
 oEmbed allows for easier embedding content from a website. It can be
@@ -1948,7 +1948,7 @@ Example configuration:
 ```yaml
 turn_shared_secret: "YOUR_SHARED_SECRET"
 ```
-----
+---
 ### `turn_username` and `turn_password`
 
 The Username and password if the TURN server needs them and does not use a token.
@@ -2367,7 +2367,7 @@ Example configuration:
 ```yaml
 session_lifetime: 24h
 ```
-----
+---
 ### `refresh_access_token_lifetime`
 
 Time that an access token remains valid for, if the session is using refresh tokens.
@@ -2423,7 +2423,7 @@ nonrefreshable_access_token_lifetime: 24h
 ```
 
 ---
-## Metrics ###
+## Metrics ##
 Config options related to metrics.
 
 ---
@@ -3671,16 +3671,22 @@ opentracing:
         false
 ```
 ---
-## Workers ##
+## Worker configuration for main process
 Configuration options related to workers.
 Workers are used to scale horizontally and distribute the load to different processes.
 
-These switches are all for the shared configuration to give the main process
-the necessary information. The configuration of the workers is described
-in detail in the [worker documentation](../../workers.md).
+The worker configuration is divided into two parts.
+
+1. These switches for the shared configuration to give the main process
+   the necessary information.
+1. And the [switches for the worker configuration file](#worker-configuration-for-workers-configuration)
+   to configure each worker them self are futher below.
+
+The manual how to configure workers is described in detail in the
+[worker documentation](../../workers.md)
 
 ---
-#### `worker_replication_secret`
+### `worker_replication_secret`
 
 A shared secret used by the replication APIs to authenticate HTTP requests
 from workers.
@@ -3706,7 +3712,7 @@ start_pushers: false
 
 It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
 in which case the work is balanced across them. Use this setting to list the pushers by
-[`worker_name`](../../workers.md#worker_name).
+[`worker_name`](#worker_name).
 
 If only one pusher worker is configured, this setting is not necessary.
 
@@ -3747,7 +3753,7 @@ federation_sender_instances:
 ---
 ### `instance_map`
 
-When using workers this should be a map from worker name to the
+When using workers this should be a map from [`worker_name`](#worker_name) to the
 HTTP replication listener of the worker, if configured.
 Not every type of worker needs a HTTP replications listener.
 
@@ -3763,7 +3769,7 @@ instance_map:
 
 Experimental: When using workers you can define which workers should
 handle event persistence and typing notifications. Any worker
-specified here must also be in the `instance_map`.
+specified here must also be in the [`instance_map`](#instance_map).
 
 Example configuration:
 ```yaml
@@ -3801,6 +3807,108 @@ redis:
   password: <secret_password>
 ```
 ---
+## Worker configuration for workers configuration
+These switches configure each worker them self with the a worker configuration file.
+
+Note also the configuration for the
+[main process above](#worker-configuration-for-main-process).
+
+The manual how to configure workers is described in detail in the
+[worker documentation](../../workers.md)
+
+---
+### `worker_app`
+
+The type of worker. The currently available worker applications are listed
+in [worker documentation](../../workers.md#available-worker-applications).
+
+The most common worker is the
+[`synapse.app.generic_worker`](../../workers.md#synapseappgeneric_worker).
+
+Example configuration:
+```yaml
+worker_app: synapse.app.generic_worker
+```
+---
+### `worker_name`
+
+A unique name for the worker. The worker needs a name to be addressed in
+further parameters and identification in log files.
+
+Example configuration:
+```yaml
+worker_name: generic_worker1
+```
+---
+### `worker_replication_host`
+
+The HTTP replication endpoint that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](#listeners).
+
+Example configuration:
+```yaml
+worker_replication_host: 127.0.0.1
+```
+---
+### `worker_replication_http_port`
+
+The HTTP replication port that it should talk to on the main Synapse process.
+The main Synapse process defines this with a `replication` resource in
+[`listeners` option](#listeners).
+
+Example configuration:
+```yaml
+worker_replication_http_port: 9093
+```
+---
+### `worker_listeners`
+
+A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
+option with an http listener, in the same way as the [`listeners` option](#listeners)
+in the shared config.
+
+Example configuration:
+```yaml
+worker_listeners:
+  - type: http
+    port: 8083
+    resources:
+      - names: [client, federation]
+```
+---
+### `worker_daemonize`
+
+Specifies whether the worker should be daemonize. If
+[systemd](../../systemd-with-workers/README.md) is used, this must not configured.
+Systemd manages daemonization itself. Defaults to `false`.
+
+Example configuration:
+```yaml
+worker_daemonize: true
+```
+---
+### `worker_pid_file`
+
+When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
+This is the same way as the[`pid_file` option](#pid_file) in the shared config.
+
+Example configuration:
+```yaml
+worker_pid_file: DATADIR/generic_worker1.pid
+```
+---
+### `worker_log_config`
+
+This option specifies a yaml python logging config file as described
+[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
+This is the same way as the [`log_config` option](#log_config) in the shared config.
+
+Example configuration:
+```yaml
+worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
+```
+---
 ## Background Updates ##
 Configuration settings related to background updates.
 
diff --git a/docs/workers.md b/docs/workers.md
index 7018b5078ccc..f05c304e4daf 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -89,11 +89,11 @@ shared configuration file.
 
 Normally, only a couple of changes are needed to make an existing configuration
 file suitable for use with workers. First, you need to enable an
-["HTTP replication listener"](usage/configuration/config_documentation.html#listeners)
+["HTTP replication listener"](usage/configuration/config_documentation.md#listeners)
 for the main process; and secondly, you need to enable
-[redis-based replication](usage/configuration/config_documentation.html#redis).
-Optionally, a shared secret can be used to authenticate HTTP
-traffic between workers. For example:
+[redis-based replication](usage/configuration/config_documentation.md#redis).
+Optionally, a [shared secret](usage/configuration/config_documentation.md#worker_replication_secret)
+can be used to authenticate HTTP traffic between workers. For example:
 
 ```yaml
 # extend the existing `listeners` section. This defines the ports that the
@@ -113,26 +113,27 @@ redis:
     enabled: true
 ```
 
-See the [configuration manual](usage/configuration/config_documentation.html)
+See the [configuration manual](usage/configuration/config_documentation.md)
 for the full documentation of each option.
 
 Under **no circumstances** should the replication listener be exposed to the
 public internet; replication traffic is:
 
 * always unencrypted
-* unauthenticated, unless `worker_replication_secret` is configured
+* unauthenticated, unless [`worker_replication_secret`](usage/configuration/config_documentation.md#worker_replication_secret)
+  is configured
 
 
 ### Worker configuration
 
 In the config file for each worker, you must specify:
- * The type of worker ([`worker_app`](#worker_app)).
+ * The type of worker ([`worker_app`](usage/configuration/config_documentation.md#worker_app)).
    The currently available worker applications are listed [below](#available-worker-applications).
- * A unique name for the worker ([`worker_name`](#worker_name)).
+ * A unique name for the worker ([`worker_name`](usage/configuration/config_documentation.md#worker_name)).
  * The HTTP replication endpoint that it should talk to on the main synapse process
-   ([`worker_replication_host`](#worker_replication_host) and
-   [`worker_replication_http_port`](#worker_replication_http_port)).
- * If handling HTTP requests, a [`worker_listeners`](#worker_listeners) option
+   ([`worker_replication_host`](usage/configuration/config_documentation.md#worker_replication_host) and
+   [`worker_replication_http_port`](usage/configuration/config_documentation.md#worker_replication_http_port)).
+ * If handling HTTP requests, a [`worker_listeners`](usage/configuration/config_documentation.md#worker_listeners) option
    with an `http` listener.
  * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for
    the main process (`worker_main_http_uri`).
@@ -150,100 +151,6 @@ plain HTTP endpoint on port 8083 separately serving various endpoints, e.g.
 Obviously you should configure your reverse-proxy to route the relevant
 endpoints to the worker (`localhost:8083` in the above example).
 
----
-#### `worker_app`
-
-The type of worker. The currently available worker applications are listed
-[below](#available-worker-applications).
-
-The most common worker is the `synapse.app.generic_worker`.
-
-Example configuration:
-```yaml
-worker_app: synapse.app.generic_worker
-```
----
-#### `worker_name`
-
-A unique name for the worker. The worker needs a name to be addressed in
-further parameters and identification in log files.
-
-Example configuration:
-```yaml
-worker_name: generic_worker1
-```
----
-#### `worker_replication_host`
-
-The HTTP replication endpoint that it should talk to on the main Synapse process.
-The main Synapse process defines this with a `replication` resource in
-[`listeners` option](#listeners).
-
-Example configuration:
-```yaml
-worker_replication_host: 127.0.0.1
-```
----
-#### `worker_replication_http_port`
-
-The HTTP replication port that it should talk to on the main Synapse process.
-The main Synapse process defines this with a `replication` resource in
-[`listeners` option](usage/configuration/config_documentation.html#listeners).
-
-Example configuration:
-```yaml
-worker_replication_http_port: 9093
-```
----
-#### `worker_listeners`
-
-A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
-option with an http listener, in the same way as the
-[`listeners` option](usage/configuration/config_documentation.html#listeners)
-in the shared config.
-
-Example configuration:
-```yaml
-worker_listeners:
-  - type: http
-    port: 8083
-    resources:
-      - names: [client, federation]
-```
----
-#### `worker_daemonize`
-
-Specifies whether the worker should be daemonize. If [systemd](systemd-with-workers/README.md)
-is used, this must not configured. Systemd manages daemonization itself. Defaults to `false`.
-
-Example configuration:
-```yaml
-worker_daemonize: true
-```
----
-#### `worker_pid_file`
-
-When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
-This is the same way as the[`pid_file` option](usage/configuration/config_documentation.html#pid_file)
-in the shared config.
-
-Example configuration:
-```yaml
-worker_pid_file: DATADIR/generic_worker1.pid
-```
----
-#### `worker_log_config`
-
-This option specifies a yaml python logging config file as described
-[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
-This is the same way as the [`log_config` option](usage/configuration/config_documentation.html#log_config)
-in the shared config.
-
-Example configuration:
-```yaml
-worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
-```
-
 ### Running Synapse with workers
 
 Finally, you need to start your worker processes. This can be done with either
@@ -385,7 +292,8 @@ For multiple workers not handling the SSO endpoints properly, see
 [#9427](https://github.com/matrix-org/synapse/issues/9427).
 
 Note that a [HTTP listener](usage/configuration/config_documentation.md#listeners)
-with `client` and `federation` `resources` must be configured in the `worker_listeners`
+with `client` and `federation` `resources` must be configured in the
+[`worker_listeners`](usage/configuration/config_documentation.md#worker_listeners)
 option in the worker config.
 
 #### Load balancing
@@ -428,9 +336,10 @@ of the main process to a particular worker.
 
 To enable this, the worker must have a
 [HTTP `replication` listener](usage/configuration/config_documentation.md#listeners) configured,
-have a `worker_name` and be listed in the `instance_map` config. The same worker
-can handle multiple streams, but unless otherwise documented, each stream can only
-have a single writer.
+have a [`worker_name`](usage/configuration/config_documentation.md#worker_name)
+and be listed in the [`instance_map`](usage/configuration/config_documentation.md#instance_map)
+config. The same worker can handle multiple streams, but unless otherwise documented,
+each stream can only have a single writer.
 
 For example, to move event persistence off to a dedicated worker, the shared
 configuration would include:
@@ -459,7 +368,13 @@ streams and the endpoints associated with them:
 
 The `events` stream experimentally supports having multiple writers, where work
 is sharded between them by room ID. Note that you *must* restart all worker
-instances when adding or removing event persisters. An example `stream_writers`
+instances when adding or removing event persisters.
+
+An `event_persister` is passed these events and is tasked with persisting them to the
+database, as well as updating the events stream. This requires linking the events to
+those already in the room DAG.
+
+An example [`stream_writers`](usage/configuration/config_documentation.md#stream_writers)
 configuration with multiple writers:
 
 ```yaml
@@ -513,16 +428,18 @@ worker. Background tasks are run periodically or started via replication. Exactl
 which tasks are configured to run depends on your Synapse configuration (e.g. if
 stats is enabled). This worker doesn't handle any REST endpoints itself.
 
-To enable this, the worker must have a `worker_name` and can be configured to run
-background tasks. For example, to move background tasks to a dedicated worker,
-the shared configuration would include:
+To enable this, the worker must have a
+[`worker_name`](usage/configuration/config_documentation.md#worker_name)
+and can be configured to run background tasks. For example, to move background tasks
+to a dedicated worker, the shared configuration would include:
 
 ```yaml
 run_background_tasks_on: background_worker
 ```
 
-You might also wish to investigate the `update_user_directory_from_worker` and
-`media_instance_running_background_jobs` settings.
+You might also wish to investigate the
+[`update_user_directory_from_worker`](#updating-the-user-directory) and
+[`media_instance_running_background_jobs`](#synapseappmedia_repository) settings.
 
 An example for a dedicated background worker instance:
 
@@ -575,11 +492,14 @@ worker application type.
 ### `synapse.app.pusher`
 
 Handles sending push notifications to sygnal and email. Doesn't handle any
-REST endpoints itself, but you should set `start_pushers: False` in the
+REST endpoints itself, but you should set
+[`start_pushers: False`](usage/configuration/config_documentation.md#start_pushers) in the
 shared configuration file to stop the main synapse sending push notifications.
 
-To run multiple instances at once the `pusher_instances` option should list all
-pusher instances by their worker name, e.g.:
+To run multiple instances at once the
+[`pusher_instances`](usage/configuration/config_documentation.md#pusher_instances)
+option should list all pusher instances by their
+[`worker_name`](usage/configuration/config_documentation.md#worker_name), e.g.:
 
 ```yaml
 pusher_instances:
@@ -609,11 +529,15 @@ Note this worker cannot be load-balanced: only one instance should be active.
 ### `synapse.app.federation_sender`
 
 Handles sending federation traffic to other servers. Doesn't handle any
-REST endpoints itself, but you should set `send_federation: False` in the
-shared configuration file to stop the main synapse sending this traffic.
+REST endpoints itself, but you should set
+[`send_federation: False`](usage/configuration/config_documentation.md#send_federation)
+in the shared configuration file to stop the main synapse sending this traffic.
 
 If running multiple federation senders then you must list each
-instance in the `federation_sender_instances` option by their `worker_name`.
+instance in the
+[`federation_sender_instances`](usage/configuration/config_documentation.md#federation_sender_instances)
+option by their
+[`worker_name`](usage/configuration/config_documentation.md#worker_name).
 All instances must be stopped and started when adding or removing instances.
 For example:
 
@@ -644,7 +568,9 @@ Handles the media repository. It can handle all endpoints starting with:
     ^/_synapse/admin/v1/quarantine_media/.*$
     ^/_synapse/admin/v1/users/.*/media$
 
-You should also set `enable_media_repo: False` in the shared configuration
+You should also set
+[`enable_media_repo: False`](usage/configuration/config_documentation.md#enable_media_repo)
+in the shared configuration
 file to stop the main synapse running background jobs related to managing the
 media repository. Note that doing so will prevent the main process from being
 able to handle the above endpoints.
diff --git a/synapse/config/logger.py b/synapse/config/logger.py
index b62b3b9205a9..d2e264d14f42 100644
--- a/synapse/config/logger.py
+++ b/synapse/config/logger.py
@@ -53,7 +53,7 @@
 # Synapse also supports structured logging for machine readable logs which can
 # be ingested by ELK stacks. See [2] for details.
 #
-# [1]: https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema
+# [1]: https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema
 # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
 
 version: 1

From 1ac4cf629b36748ea927ad720e31ff11d3ef74f2 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Mon, 24 Oct 2022 17:26:57 +0200
Subject: [PATCH 06/25] newsfile and small update

---
 changelog.d/14086.doc | 2 +-
 docs/workers.md       | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/changelog.d/14086.doc b/changelog.d/14086.doc
index de0e1715d6e3..a8eb2eb3c8d8 100644
--- a/changelog.d/14086.doc
+++ b/changelog.d/14086.doc
@@ -1 +1 @@
-Add workers settings to [configuration manual](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#workers).
+Add workers settings to [configuration manual](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#worker-configuration-for-workers-configuration).
\ No newline at end of file
diff --git a/docs/workers.md b/docs/workers.md
index f05c304e4daf..d0394d524136 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -374,6 +374,13 @@ An `event_persister` is passed these events and is tasked with persisting them t
 database, as well as updating the events stream. This requires linking the events to
 those already in the room DAG.
 
+The `event_persister` should not be mistaken for the `event_creator`.
+An `event_creator` listening for requests that create new events, then creates
+`EventBase` objects based off those requests. It will then pass those along over
+HTTP replication to any configured event stream writers responsible for persisting
+those events (or the main process if none are configured). The `event_creator`
+is part of the [`synapse.app.generic_worker`](#synapse.app.generic_worker).
+
 An example [`stream_writers`](usage/configuration/config_documentation.md#stream_writers)
 configuration with multiple writers:
 

From 628a448e615c8f63468774f8df6d185d1e69723d Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:23:25 +0200
Subject: [PATCH 07/25] Apply suggestions from code review

Co-authored-by: David Robertson <david.m.robertson1@gmail.com>
---
 .../configuration/config_documentation.md     | 60 +++++++++++--------
 docs/workers.md                               |  2 +-
 2 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 420c682fb792..f392ff179c82 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -2423,7 +2423,7 @@ nonrefreshable_access_token_lifetime: 24h
 ```
 
 ---
-## Metrics ##
+## Metrics
 Config options related to metrics.
 
 ---
@@ -3671,27 +3671,30 @@ opentracing:
         false
 ```
 ---
-## Worker configuration for main process
+## Coordinating workers
 Configuration options related to workers.
-Workers are used to scale horizontally and distribute the load to different processes.
+A Synapse deployment can scale horizontally by running multiple Synapse processes
+called _workers_. Incoming requests are distributed between workers to handle higher
+loads. Some workers are privileged and can accept requests from other workers.
 
-The worker configuration is divided into two parts.
+As a result, the worker configuration is divided into two parts.
 
-1. These switches for the shared configuration to give the main process
-   the necessary information.
-1. And the [switches for the worker configuration file](#worker-configuration-for-workers-configuration)
-   to configure each worker them self are futher below.
+1. The first part (in this section of the manual) defines which shardable tasks
+   are delegated to privileged workers. This allows unprivileged workers to make
+   request a privileged worker to act on their behalf.
+1. [The second part](#worker-configuration-for-workers-configuration)
+   controls the behaviour of individual workers in isolation.
 
-The manual how to configure workers is described in detail in the
-[worker documentation](../../workers.md)
+For guidance on setting up workers, see the [worker documentation](../../workers.md).
 
 ---
 ### `worker_replication_secret`
 
-A shared secret used by the replication APIs to authenticate HTTP requests
-from workers.
+A shared secret used by the replication APIs on the main process to authenticate
+HTTP requests from workers.
 
-By default this is unused and traffic is not authenticated.
+The default, this value is omitted (equivalently `null`), which means that 
+traffic between the workers and the main process is not authenticated.
 
 Example configuration:
 ```yaml
@@ -3726,7 +3729,7 @@ pusher_instances:
 ### `send_federation`
 
 Controls sending of outbound federation transactions on the main process.
-Set to false if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
+Set to `false` if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
 Defaults to `true`.
 
 Example configuration:
@@ -3807,14 +3810,13 @@ redis:
   password: <secret_password>
 ```
 ---
-## Worker configuration for workers configuration
+## Individual worker configuration
 These switches configure each worker them self with the a worker configuration file.
 
-Note also the configuration for the
-[main process above](#worker-configuration-for-main-process).
+Note also the configuration above for
+[coordinating a cluster of workers](#coordinating-workers).
 
-The manual how to configure workers is described in detail in the
-[worker documentation](../../workers.md)
+For guidance on setting up workers, see the [worker documentation](../../workers.md).
 
 ---
 ### `worker_app`
@@ -3879,9 +3881,11 @@ worker_listeners:
 ---
 ### `worker_daemonize`
 
-Specifies whether the worker should be daemonize. If
-[systemd](../../systemd-with-workers/README.md) is used, this must not configured.
-Systemd manages daemonization itself. Defaults to `false`.
+Specifies whether the worker should be started as a [daemon process](TODO_FIND_A_LINK).
+If Synapse is being managed by [systemd](../../systemd-with-workers/README.md), this option 
+must be omitted or set to `false`.
+
+Defaults to `false`.
 
 Example configuration:
 ```yaml
@@ -3890,8 +3894,14 @@ worker_daemonize: true
 ---
 ### `worker_pid_file`
 
-When running Synapse worker as a daemon, the file to store the pid in. Defaults to none.
-This is the same way as the[`pid_file` option](#pid_file) in the shared config.
+When running a worker as a daemon, we need a place to store the 
+[PID](https://en.wikipedia.org/wiki/Process_identifier) of the worker.
+This option defines the location of that "pid file".
+
+This option is required if `worker_daemonize` is `true` and ignored 
+otherwise. It has no default.
+
+See also the [`pid_file` option](#pid_file) option for the main Synapse process.
 
 Example configuration:
 ```yaml
@@ -3902,7 +3912,7 @@ worker_pid_file: DATADIR/generic_worker1.pid
 
 This option specifies a yaml python logging config file as described
 [here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
-This is the same way as the [`log_config` option](#log_config) in the shared config.
+See also the [`log_config` option](#log_config) option for the main Synapse process.
 
 Example configuration:
 ```yaml
diff --git a/docs/workers.md b/docs/workers.md
index d0394d524136..82e5c792d951 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -435,7 +435,7 @@ worker. Background tasks are run periodically or started via replication. Exactl
 which tasks are configured to run depends on your Synapse configuration (e.g. if
 stats is enabled). This worker doesn't handle any REST endpoints itself.
 
-To enable this, the worker must have a
+To enable this, the worker must have a unique
 [`worker_name`](usage/configuration/config_documentation.md#worker_name)
 and can be configured to run background tasks. For example, to move background tasks
 to a dedicated worker, the shared configuration would include:

From 327c81c5bfd4c9ddb7a3f76971c884045459a225 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:28:19 +0200
Subject: [PATCH 08/25] update url to python logger

---
 docs/sample_log_config.yaml                      | 2 +-
 docs/usage/configuration/config_documentation.md | 4 ++--
 synapse/config/logger.py                         | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/sample_log_config.yaml b/docs/sample_log_config.yaml
index df18726f5506..6339160d0022 100644
--- a/docs/sample_log_config.yaml
+++ b/docs/sample_log_config.yaml
@@ -6,7 +6,7 @@
 # Synapse also supports structured logging for machine readable logs which can
 # be ingested by ELK stacks. See [2] for details.
 #
-# [1]: https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema
+# [1]: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema
 # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
 
 version: 1
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index f392ff179c82..cd793f2994fb 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -1339,7 +1339,7 @@ Config options related to logging.
 ### `log_config`
 
 This option specifies a yaml python logging config file as described
-[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
+[here](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema).
 
 Example configuration:
 ```yaml
@@ -3911,7 +3911,7 @@ worker_pid_file: DATADIR/generic_worker1.pid
 ### `worker_log_config`
 
 This option specifies a yaml python logging config file as described
-[here](https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema).
+[here](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema).
 See also the [`log_config` option](#log_config) option for the main Synapse process.
 
 Example configuration:
diff --git a/synapse/config/logger.py b/synapse/config/logger.py
index d2e264d14f42..94d115041526 100644
--- a/synapse/config/logger.py
+++ b/synapse/config/logger.py
@@ -53,7 +53,7 @@
 # Synapse also supports structured logging for machine readable logs which can
 # be ingested by ELK stacks. See [2] for details.
 #
-# [1]: https://docs.python.org/3.11/library/logging.config.html#configuration-dictionary-schema
+# [1]: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema
 # [2]: https://matrix-org.github.io/synapse/latest/structured_logging.html
 
 version: 1

From d12e0068cd85744537b8c2cadd02173f4572a86f Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:30:12 +0200
Subject: [PATCH 09/25] update headlines

---
 .../configuration/config_documentation.md     | 36 +++++++++----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index cd793f2994fb..942e241384ec 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -99,7 +99,7 @@ modules:
     config: {}
 ```
 ---
-## Server ##
+## Server
 
 Define your homeserver name and other base options.
 
@@ -570,7 +570,7 @@ Example configuration:
 delete_stale_devices_after: 1y
 ```
 
-## Homeserver blocking ##
+## Homeserver blocking
 Useful options for Synapse admins.
 
 ---
@@ -922,7 +922,7 @@ retention:
       interval: 1d
 ```
 ---
-## TLS ##
+## TLS
 
 Options related to TLS.
 
@@ -1012,7 +1012,7 @@ federation_custom_ca_list:
   - myCA3.pem
 ```
 ---
-## Federation ##
+## Federation
 
 Options related to federation.
 
@@ -1071,7 +1071,7 @@ Example configuration:
 allow_device_name_lookup_over_federation: true
 ```
 ---
-## Caching ##
+## Caching
 
 Options related to caching.
 
@@ -1185,7 +1185,7 @@ file in Synapse's `contrib` directory, you can send a `SIGHUP` signal by using
 `systemctl reload matrix-synapse`.
 
 ---
-## Database ##
+## Database
 Config options related to database settings.
 
 ---
@@ -1332,7 +1332,7 @@ databases:
       cp_max: 10
 ```
 ---
-## Logging ##
+## Logging
 Config options related to logging.
 
 ---
@@ -1346,7 +1346,7 @@ Example configuration:
 log_config: "CONFDIR/SERVERNAME.log.config"
 ```
 ---
-## Ratelimiting ##
+## Ratelimiting
 Options related to ratelimiting in Synapse.
 
 Each ratelimiting configuration is made of two parameters:
@@ -1577,7 +1577,7 @@ Example configuration:
 federation_rr_transactions_per_room_per_second: 40
 ```
 ---
-## Media Store ##
+## Media Store
 Config options related to Synapse's media store.
 
 ---
@@ -1878,7 +1878,7 @@ oembed:
     - oembed/my_providers.json
 ```
 ---
-## Captcha ##
+## Captcha
 
 See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha.
 
@@ -1927,7 +1927,7 @@ Example configuration:
 recaptcha_siteverify_api: "https://my.recaptcha.site"
 ```
 ---
-## TURN ##
+## TURN
 Options related to adding a TURN server to Synapse.
 
 ---
@@ -2520,7 +2520,7 @@ Example configuration:
 report_stats_endpoint: https://example.com/report-usage-stats/push
 ```
 ---
-## API Configuration ##
+## API Configuration
 Config settings related to the client/server API
 
 ---
@@ -2620,7 +2620,7 @@ Example configuration:
 form_secret: <PRIVATE STRING>
 ```
 ---
-## Signing Keys ##
+## Signing Keys
 Config options relating to signing keys
 
 ---
@@ -2729,7 +2729,7 @@ Example configuration:
 key_server_signing_keys_path: "key_server_signing_keys.key"
 ```
 ---
-## Single sign-on integration ##
+## Single sign-on integration
 
 The following settings can be used to make Synapse use a single sign-on
 provider for authentication, instead of its internal password database.
@@ -3349,7 +3349,7 @@ email:
     email_validation: "[%(server_name)s] Validate your email"
 ```
 ---
-## Push ##
+## Push
 Configuration settings related to push notifications
 
 ---
@@ -3382,7 +3382,7 @@ push:
   group_unread_count_by_room: false
 ```
 ---
-## Rooms ##
+## Rooms
 Config options relating to rooms.
 
 ---
@@ -3628,7 +3628,7 @@ default_power_level_content_override:
 ```
 
 ---
-## Opentracing ##
+## Opentracing
 Configuration options related to Opentracing support.
 
 ---
@@ -3919,7 +3919,7 @@ Example configuration:
 worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
 ```
 ---
-## Background Updates ##
+## Background Updates
 Configuration settings related to background updates.
 
 ---

From c1067475f3e71128cc078334424e122580a98a9b Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:36:31 +0200
Subject: [PATCH 10/25] update links after headline change

---
 changelog.d/14086.doc                            | 2 +-
 docs/usage/configuration/config_documentation.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/changelog.d/14086.doc b/changelog.d/14086.doc
index a8eb2eb3c8d8..5b4b938759d0 100644
--- a/changelog.d/14086.doc
+++ b/changelog.d/14086.doc
@@ -1 +1 @@
-Add workers settings to [configuration manual](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#worker-configuration-for-workers-configuration).
\ No newline at end of file
+Add workers settings to [configuration manual](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#individual-worker-configuration).
\ No newline at end of file
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 942e241384ec..5840d1d2c2b2 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3682,7 +3682,7 @@ As a result, the worker configuration is divided into two parts.
 1. The first part (in this section of the manual) defines which shardable tasks
    are delegated to privileged workers. This allows unprivileged workers to make
    request a privileged worker to act on their behalf.
-1. [The second part](#worker-configuration-for-workers-configuration)
+1. [The second part](#individual-worker-configuration)
    controls the behaviour of individual workers in isolation.
 
 For guidance on setting up workers, see the [worker documentation](../../workers.md).

From 955dab6b61590b4e44ed04b149f8c993d3c35ab2 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:47:09 +0200
Subject: [PATCH 11/25] remove link from `daemon process`

There is no docs in Synapse for this
---
 docs/usage/configuration/config_documentation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 5840d1d2c2b2..20958902b627 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3881,7 +3881,7 @@ worker_listeners:
 ---
 ### `worker_daemonize`
 
-Specifies whether the worker should be started as a [daemon process](TODO_FIND_A_LINK).
+Specifies whether the worker should be started as a daemon process.
 If Synapse is being managed by [systemd](../../systemd-with-workers/README.md), this option 
 must be omitted or set to `false`.
 

From 18d692ab400a9fbebbfc3b822852bfd0c1565767 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:49:46 +0200
Subject: [PATCH 12/25] Apply suggestions from code review

Co-authored-by: David Robertson <david.m.robertson1@gmail.com>
---
 docs/usage/configuration/config_documentation.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 20958902b627..2a6bc118e2d7 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3811,7 +3811,8 @@ redis:
 ```
 ---
 ## Individual worker configuration
-These switches configure each worker them self with the a worker configuration file.
+These options configure an individual worker, in its worker configuration file.
+They should be not be provided when configuring the main process.
 
 Note also the configuration above for
 [coordinating a cluster of workers](#coordinating-workers).

From 1d677f32a8ee0197239023b5e09574d4d7468d8a Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:50:21 +0200
Subject: [PATCH 13/25] Apply suggestions from code review

Co-authored-by: David Robertson <david.m.robertson1@gmail.com>
---
 docs/workers.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/workers.md b/docs/workers.md
index 82e5c792d951..36544c5f8ee9 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -374,12 +374,13 @@ An `event_persister` is passed these events and is tasked with persisting them t
 database, as well as updating the events stream. This requires linking the events to
 those already in the room DAG.
 
-The `event_persister` should not be mistaken for the `event_creator`.
-An `event_creator` listening for requests that create new events, then creates
-`EventBase` objects based off those requests. It will then pass those along over
-HTTP replication to any configured event stream writers responsible for persisting
-those events (or the main process if none are configured). The `event_creator`
-is part of the [`synapse.app.generic_worker`](#synapse.app.generic_worker).
+An `event_persister` should not be mistaken for an `event_creator`.
+An `event_creator` listens for requests from clients to create new events and does
+so. It will then pass those events over HTTP replication to any configured event
+persisters (or the main process if none are configured).
+
+Note that `event_creator`s and `event_persister`s are implemented using the same
+[`synapse.app.generic_worker`](#synapse.app.generic_worker).
 
 An example [`stream_writers`](usage/configuration/config_documentation.md#stream_writers)
 configuration with multiple writers:

From 2c91c5a1b05788e0ff8d4868a60db0d02864b2ed Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 20:54:46 +0200
Subject: [PATCH 14/25] update `event persister` doc

---
 docs/workers.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/workers.md b/docs/workers.md
index 36544c5f8ee9..0c202de3d87a 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -366,13 +366,16 @@ streams and the endpoints associated with them:
 
 ##### The `events` stream
 
-The `events` stream experimentally supports having multiple writers, where work
-is sharded between them by room ID. Note that you *must* restart all worker
-instances when adding or removing event persisters.
-
-An `event_persister` is passed these events and is tasked with persisting them to the
-database, as well as updating the events stream. This requires linking the events to
-those already in the room DAG.
+The `events` stream experimentally supports having multiple writer workers, where load
+is sharded between them by room ID. Each writer is called an _event persister_. They are
+responsible for
+- receiving new events,
+- linking them to those already in the room DAG,
+- persisting them to the DB, and finally
+- updating the events stream.
+
+Because load is sharded in this way, you *must* restart all worker instances when 
+adding or removing event persisters.
 
 An `event_persister` should not be mistaken for an `event_creator`.
 An `event_creator` listens for requests from clients to create new events and does

From b0a20d15e50c377ff91a81087c068a631c4c3c85 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 21:15:30 +0200
Subject: [PATCH 15/25] extend example for `federation_sender_instances` and
 `pusher_instances`

---
 docs/usage/configuration/config_documentation.md | 2 ++
 docs/workers.md                                  | 6 ++++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 2a6bc118e2d7..fbd9afcb6b96 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3721,6 +3721,7 @@ If only one pusher worker is configured, this setting is not necessary.
 
 Example configuration:
 ```yaml
+start_pushers: false
 pusher_instances:
   - pusher_worker1
   - pusher_worker2
@@ -3750,6 +3751,7 @@ events may be dropped).
 
 Example configuration:
 ```yaml
+send_federation: false
 federation_sender_instances:
   - federation_sender1
 ```
diff --git a/docs/workers.md b/docs/workers.md
index 0c202de3d87a..26890ae5dd38 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -504,7 +504,7 @@ worker application type.
 
 Handles sending push notifications to sygnal and email. Doesn't handle any
 REST endpoints itself, but you should set
-[`start_pushers: False`](usage/configuration/config_documentation.md#start_pushers) in the
+[`start_pushers: false`](usage/configuration/config_documentation.md#start_pushers) in the
 shared configuration file to stop the main synapse sending push notifications.
 
 To run multiple instances at once the
@@ -513,6 +513,7 @@ option should list all pusher instances by their
 [`worker_name`](usage/configuration/config_documentation.md#worker_name), e.g.:
 
 ```yaml
+start_pushers: false
 pusher_instances:
     - pusher_worker1
     - pusher_worker2
@@ -541,7 +542,7 @@ Note this worker cannot be load-balanced: only one instance should be active.
 
 Handles sending federation traffic to other servers. Doesn't handle any
 REST endpoints itself, but you should set
-[`send_federation: False`](usage/configuration/config_documentation.md#send_federation)
+[`send_federation: false`](usage/configuration/config_documentation.md#send_federation)
 in the shared configuration file to stop the main synapse sending this traffic.
 
 If running multiple federation senders then you must list each
@@ -553,6 +554,7 @@ All instances must be stopped and started when adding or removing instances.
 For example:
 
 ```yaml
+send_federation: false
 federation_sender_instances:
     - federation_sender1
     - federation_sender2

From 17ec5d3cf1a6398480647753ed466f955d2466ee Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Wed, 26 Oct 2022 21:29:13 +0200
Subject: [PATCH 16/25] more infos about stream writers

---
 docs/usage/configuration/config_documentation.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index fbd9afcb6b96..75774e1f0918 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3760,7 +3760,9 @@ federation_sender_instances:
 
 When using workers this should be a map from [`worker_name`](#worker_name) to the
 HTTP replication listener of the worker, if configured.
-Not every type of worker needs a HTTP replications listener.
+Only `synapse.app.generic_worker` as [`stream_writers`](../../workers.md#stream-writers)
+needs a HTTP replications listener. It must also be specified the
+[`instance_map`](#instance_map).
 
 Example configuration:
 ```yaml
@@ -3776,6 +3778,9 @@ Experimental: When using workers you can define which workers should
 handle event persistence and typing notifications. Any worker
 specified here must also be in the [`instance_map`](#instance_map).
 
+See the list of available streams in the
+[worker documentation](../../workers.md#stream-writers).
+
 Example configuration:
 ```yaml
 stream_writers:

From 76f8b5fd95f862feca2dbb7b00beb4578296e0bd Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 07:38:54 +0200
Subject: [PATCH 17/25] add link to DAG

---
 docs/workers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/workers.md b/docs/workers.md
index 26890ae5dd38..5e1b9ba220e8 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -370,7 +370,7 @@ The `events` stream experimentally supports having multiple writer workers, wher
 is sharded between them by room ID. Each writer is called an _event persister_. They are
 responsible for
 - receiving new events,
-- linking them to those already in the room DAG,
+- linking them to those already in the room [DAG](development/room-dag-concepts.md),
 - persisting them to the DB, and finally
 - updating the events stream.
 

From a3ad96aefc518e3faf85de406df36a92f83d7c50 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 08:03:20 +0200
Subject: [PATCH 18/25] small rewording

---
 docs/usage/configuration/config_documentation.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 75774e1f0918..d55b60351617 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3775,8 +3775,8 @@ instance_map:
 ### `stream_writers`
 
 Experimental: When using workers you can define which workers should
-handle event persistence and typing notifications. Any worker
-specified here must also be in the [`instance_map`](#instance_map).
+handle write streams such as event persistence and typing notifications.
+Any worker specified here must also be in the [`instance_map`](#instance_map).
 
 See the list of available streams in the
 [worker documentation](../../workers.md#stream-writers).

From 6c9cea2a942a15dd0d5893c1700b59f3dbd74759 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 13:19:45 +0200
Subject: [PATCH 19/25] Apply suggestions from code review

Co-authored-by: David Robertson <david.m.robertson1@gmail.com>
---
 docs/usage/configuration/config_documentation.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index d55b60351617..21ef609e69e3 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3760,9 +3760,10 @@ federation_sender_instances:
 
 When using workers this should be a map from [`worker_name`](#worker_name) to the
 HTTP replication listener of the worker, if configured.
-Only `synapse.app.generic_worker` as [`stream_writers`](../../workers.md#stream-writers)
-needs a HTTP replications listener. It must also be specified the
-[`instance_map`](#instance_map).
+Each worker declared under [`stream_writers`](../../workers.md#stream-writers) needs 
+a HTTP replication listener, and that listener should be included in the `instance_map`.
+(The main process also needs an HTTP replication listener, but it should not be 
+listed in the `instance_map`.)
 
 Example configuration:
 ```yaml

From 0f9b29fdf9e1caac660b2e2fde61cb5e69bca25f Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 14:12:21 +0200
Subject: [PATCH 20/25] Apply suggestions from code review

Co-authored-by: David Robertson <david.m.robertson1@gmail.com>
---
 docs/usage/configuration/config_documentation.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 21ef609e69e3..2787ed9fe955 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3672,7 +3672,8 @@ opentracing:
 ```
 ---
 ## Coordinating workers
-Configuration options related to workers.
+Configuration options related to workers which belong in the main config file
+(usually called `homeserver.yaml`).
 A Synapse deployment can scale horizontally by running multiple Synapse processes
 called _workers_. Incoming requests are distributed between workers to handle higher
 loads. Some workers are privileged and can accept requests from other workers.

From 5045ca0edf89f691ca009fbac3d44194ddb22fe6 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 14:23:07 +0200
Subject: [PATCH 21/25] update `pusher_instances`

---
 docs/usage/configuration/config_documentation.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 2787ed9fe955..4cfe95cf57e7 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3716,9 +3716,12 @@ start_pushers: false
 
 It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
 in which case the work is balanced across them. Use this setting to list the pushers by
-[`worker_name`](#worker_name).
+[`worker_name`](#worker_name). Ensure the main process and all pusher workers are
+restarted after changing this option.
 
-If only one pusher worker is configured, this setting is not necessary.
+If no or only one pusher worker is configured, this setting is not necessary.
+The main process will send out push notifications by default if you do not disable
+it by setting [`start_pushers: false`](#start_pushers).
 
 Example configuration:
 ```yaml

From a943440797467342ad132cadeb5d98647fc4ab53 Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 14:27:46 +0200
Subject: [PATCH 22/25] update `worker_listeners`

---
 docs/usage/configuration/config_documentation.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 4cfe95cf57e7..7da779bfc7f0 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3879,10 +3879,14 @@ worker_replication_http_port: 9093
 ---
 ### `worker_listeners`
 
-A worker can handle HTTP requests. If handling HTTP requests, a `worker_listeners`
-option with an http listener, in the same way as the [`listeners` option](#listeners)
+A worker can handle HTTP requests. To do so, a `worker_listeners` option 
+must be declared, in the same way as the [`listeners` option](#listeners) 
 in the shared config.
 
+Workers declared in [`stream_writers`](#stream_writers) will need to include a
+`replication` listener here, in order to accept internal HTTP requests from
+other workers.
+
 Example configuration:
 ```yaml
 worker_listeners:

From a214ee89e8c0702c585897484a58fd5b9c94f0fd Mon Sep 17 00:00:00 2001
From: dklimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 14:28:56 +0200
Subject: [PATCH 23/25] update `stream_writers`

---
 docs/usage/configuration/config_documentation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 7da779bfc7f0..848358861d7b 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3780,7 +3780,7 @@ instance_map:
 ### `stream_writers`
 
 Experimental: When using workers you can define which workers should
-handle write streams such as event persistence and typing notifications.
+handling writing to streams such as event persistence and typing notifications.
 Any worker specified here must also be in the [`instance_map`](#instance_map).
 
 See the list of available streams in the

From c0434bde3b8acbbb283e243fd78e35f85177b1e0 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Thu, 27 Oct 2022 14:35:57 +0200
Subject: [PATCH 24/25] Update `worker_name`

---
 docs/usage/configuration/config_documentation.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 848358861d7b..083de0ba61a7 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3848,7 +3848,8 @@ worker_app: synapse.app.generic_worker
 ### `worker_name`
 
 A unique name for the worker. The worker needs a name to be addressed in
-further parameters and identification in log files.
+further parameters and identification in log files. We strongly recommend
+giving each worker a unique `worker_name`.
 
 Example configuration:
 ```yaml

From 8394c3eb7d6d84e149e73f4ee7e920086ab97f5a Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Thu, 27 Oct 2022 13:48:45 +0100
Subject: [PATCH 25/25] Fix dmr typo in `stream_writers`!!

---
 docs/usage/configuration/config_documentation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 083de0ba61a7..fb5eb42c5297 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -3780,7 +3780,7 @@ instance_map:
 ### `stream_writers`
 
 Experimental: When using workers you can define which workers should
-handling writing to streams such as event persistence and typing notifications.
+handle writing to streams such as event persistence and typing notifications.
 Any worker specified here must also be in the [`instance_map`](#instance_map).
 
 See the list of available streams in the