feat(synapse): add ansible role

roles/synapse/docs/logging.md

@@ -0,0 +1,48 @@
+# `synapse` logging configuration
+
+Synapse uses a `buffer` handler per default, which flushes
+periodically, but flushes logs immediately for log events
+with a level greater or equal to WARNING.
+
+To set your desired log level, specify it in `synapse_log_config_root_level`.
+
+## Formatters
+
+By default, the upstream `precise` formatter is availabe. To define and use
+more formatters, extend `synapse_log_config_formatters` like this:
+
+```yaml
+synapse_log_config_formatters_custom_json:
+  custom_json:
+    format: >-
+      {"lineno": %(lineno)d, "level": "%(levelname)s", "req_id": "%(request)s", "msg": "%(message)s"}
+synapse_log_config_formatters: >-2
+  {{
+    ({ synapse_log_config_formatters_precise_name: synapse_log_config_formatters_precise })
+    | combine(synapse_log_config_formatters_custom_json)
+  }}
+
+# Set handlers to use your formatter like this
+synapse_log_config_handlers_file_formatter: custom_json
+synapse_log_config_handlers_console_formatter: custom_json
+```
+
+## Handlers
+
+For modifying the built-in `file`/`buffer`/`console` handlers, see
+[the defaults in `../defaults/main/log.config.yml`](../defaults/main/log.config.yml).
+
+### Containers
+
+For typical container setups, it is often recommended to log all
+logs to `stdout`/`stderr`. This can be easily archieved by setting
+`synapse_log_config_root_handlers: [ synapse_log_config_handlers_console_name ]`.
+
+## Child loggers
+
+To set a different configuration / log level for child loggers of
+the root logger (currently, this is only `synapse.storage.SQL`),
+override `synapse_log_config_loggers` directly or for the SQL loggers,
+set the level in `synapse_log_config_loggers_synapse_storage_sql_level`
+(which defaults to `synapse_log_config_root_level`).
+