From 6902e9ff2bee4b6e0c2424b88bdac607a2e6b440 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 6 Apr 2022 13:41:14 -0400 Subject: [PATCH] Remove docs for converting a legacy structured logging config. (#12392) And update the upgrade notes to point at old versions of the documentation. --- changelog.d/12392.doc | 1 + docs/structured_logging.md | 79 -------------------------------------- docs/upgrade.md | 4 +- 3 files changed, 3 insertions(+), 81 deletions(-) create mode 100644 changelog.d/12392.doc diff --git a/changelog.d/12392.doc b/changelog.d/12392.doc new file mode 100644 index 0000000000..6a2f522bf6 --- /dev/null +++ b/changelog.d/12392.doc @@ -0,0 +1 @@ +Remove documentation for converting a legacy structured logging configuration to the new format. diff --git a/docs/structured_logging.md b/docs/structured_logging.md index 805c867653..a6667e1a11 100644 --- a/docs/structured_logging.md +++ b/docs/structured_logging.md @@ -78,82 +78,3 @@ loggers: The above logging config will set Synapse as 'INFO' logging level by default, with the SQL layer at 'WARNING', and will log JSON formatted messages to a remote endpoint at 10.1.2.3:9999. - -## Upgrading from legacy structured logging configuration - -Versions of Synapse prior to v1.54.0 automatically converted the legacy -structured logging configuration, which was deprecated in v1.23.0, to the standard -library logging configuration. - -The following reference can be used to update your configuration. Based on the -drain `type`, we can pick a new handler: - -1. For a type of `console`, `console_json`, or `console_json_terse`: a handler - with a class of `logging.StreamHandler` and a `stream` of `ext://sys.stdout` - or `ext://sys.stderr` should be used. -2. For a type of `file` or `file_json`: a handler of `logging.FileHandler` with - a location of the file path should be used. -3. For a type of `network_json_terse`: a handler of `synapse.logging.RemoteHandler` - with the host and port should be used. - -Then based on the drain `type` we can pick a new formatter: - -1. For a type of `console` or `file` no formatter is necessary. -2. For a type of `console_json` or `file_json`: a formatter of - `synapse.logging.JsonFormatter` should be used. -3. For a type of `console_json_terse` or `network_json_terse`: a formatter of - `synapse.logging.TerseJsonFormatter` should be used. - -For each new handler and formatter they should be added to the logging configuration -and then assigned to either a logger or the root logger. - -An example legacy configuration: - -```yaml -structured: true - -loggers: - synapse: - level: INFO - synapse.storage.SQL: - level: WARNING - -drains: - console: - type: console - location: stdout - file: - type: file_json - location: homeserver.log -``` - -Would be converted into a new configuration: - -```yaml -version: 1 - -formatters: - json: - class: synapse.logging.JsonFormatter - -handlers: - console: - class: logging.StreamHandler - stream: ext://sys.stdout - file: - class: logging.FileHandler - formatter: json - filename: homeserver.log - -loggers: - synapse: - level: INFO - handlers: [console, file] - synapse.storage.SQL: - level: WARNING -``` - -The new logging configuration is a bit more verbose, but significantly more -flexible. It allows for configuration that were not previously possible, such as -sending plain logs over the network, or using different handlers for different -modules. diff --git a/docs/upgrade.md b/docs/upgrade.md index de3444930e..f0c0a3998d 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -160,7 +160,7 @@ please upgrade Mjolnir to version 1.3.2 or later before upgrading Synapse. This release removes support for the `structured: true` logging configuration which was deprecated in Synapse v1.23.0. If your logging configuration contains `structured: true` then it should be modified based on the -[structured logging documentation](structured_logging.md). +[structured logging documentation](https://matrix-org.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). # Upgrading to v1.53.0 @@ -777,7 +777,7 @@ lock down external access to the Admin API endpoints. This release deprecates use of the `structured: true` logging configuration for structured logging. If your logging configuration contains `structured: true` then it should be modified based on the -[structured logging documentation](structured_logging.md). +[structured logging documentation](https://matrix-org.github.io/synapse/v1.56/structured_logging.html#upgrading-from-legacy-structured-logging-configuration). The `structured` and `drains` logging options are now deprecated and should be replaced by standard logging configuration of `handlers` and