From 2a85439e40415baf0e522d5c95afc23701191c0c Mon Sep 17 00:00:00 2001
From: Hans van Zijst <hans@procolix.com>
Date: Wed, 18 Dec 2024 12:49:45 +0100
Subject: [PATCH] Added a bit of worker documentation.

---
 matrix/synapse/workers.md | 128 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/matrix/synapse/workers.md b/matrix/synapse/workers.md
index d4f585f..2398301 100644
--- a/matrix/synapse/workers.md
+++ b/matrix/synapse/workers.md
@@ -240,6 +240,134 @@ instance_map:
 
 ## Defining a worker
 
+Every working starts with the normal configuration files, and then loads its
+own. We put those files under `/etc/matrix-synapse/workers`. You have to
+create that directory, and make sure Synapse can read them. Being
+profesionally paranoid, we restrict access to that directory and the files in
+it:
+
+```
+mkdir /etc/matrix-synapse/workers
+chown matrix-synapse:matrix-synapse /etc/matrix-synapse/workers
+chmod 750 /etc/matrix-synapse-workers
+```
+
+Workers look very much the same, very little configuration is needed. This is
+what you need:
+
+* name
+* replication socket (not every worker needs this)
+* inbound socket (not every worker needs this)
+* log configuration
+
+One worker we use handles the login actions, this is how it's configured:
+
+```
+worker_app: "synapse.app.generic_worker"
+worker_name: "login"
+worker_log_config: "/etc/matrix-synapse/logconf.d/login.yaml"
+
+worker_listeners:
+  - path: "/run/matrix-synapse/inbound_login.sock"
+    type: http
+    resources:
+      - names:
+        - client
+        - consent
+        - federation
+
+  - path: "/run/matrix-synapse/replication_login.sock"
+    type: http
+    resources:
+      - names: [replication]
+```
+
+First listener is the socket where nginx sends all traffic related to logins
+to. You have to configure nginx to do that, we'll get to that later.
+
+First line defines the type of worker. In the past there were quite a few
+different types, but most of them have been phased out in favour of one
+generic worker.
+
+The `worker_log_config` defines how and where the worker logs. Of course you'll
+need to configure that too, see further.
+
+The first `listener` is the inbound socket, that nginx uses to forward login
+related traffic to. Make sure nginx can write to this socket. The
+`resources` vary between workers.
+
+The second `listener` is used for communication with the other workers and the
+main thread. The only `resource` it needs is `replication`. This socket needs
+to be listed in the `instance_map` in the main thread.
+
+Of course, if you need to scale up to the point where you need more than one
+machine, these listeners can no longer use UNIX sockets, but will have to use
+the network. This creates extra overhead, so you want to use sockets whenever
+possible.
+
+
+## Worker logging
+
+As stated before, you configure the logging of workers in a separate yaml
+file. As with the definitions of the workers themselves, you need a directory for
+that. We'll use `/etc/matrix-synapse/logconf.d` for that; make it and fix the
+permissions.
+
+There's a lot you can configure for logging, but for now we'll give every
+worker the same layout. Here's the configuration for the `login` worker:
+
+```
+version: 1
+formatters:
+  precise:
+    format: '%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(request)s
+- %(message)s'
+handlers:
+  file:
+    class: logging.handlers.TimedRotatingFileHandler
+    formatter: precise
+    filename: /var/log/matrix-synapse/login.log
+    when: midnight
+    backupCount: 3
+    encoding: utf8
+
+  buffer:
+    class: synapse.logging.handlers.PeriodicallyFlushingMemoryHandler
+    target: file
+    capacity: 10
+    flushLevel: 30
+    period: 5
+
+loggers:
+  synapse.metrics:
+    level: WARN
+    handlers: [buffer]
+  synapse.replication.tcp:
+    level: WARN
+    handlers: [buffer]
+  synapse.util.caches.lrucache:
+    level: WARN
+    handlers: [buffer]
+  twisted:
+    level: WARN
+    handlers: [buffer]
+  synapse:
+    level: INFO
+    handlers: [buffer]
+
+root:
+  level: INFO
+  handlers: [buffer]
+```
+
+The only thing you need to change if the filename to which the logs are
+written. You could create only one configuration and use that in every worker,
+but that would mean all logs will end up in the same file, which may not be
+what you want.
+
+See the [Python
+documentation](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema)
+for all the ins and outs of logging.