From 05c34201e22138533c9d960039efbedc7c9d3ee6 Mon Sep 17 00:00:00 2001 From: zeripath Date: Sat, 10 Oct 2020 16:19:50 +0100 Subject: [PATCH] Change default log configuration (#13088) * Change default log configuration This PR changes the install page and the docker default logging configuration to match the suggested configuration that I repeatedly end up suggesting on issues. It further improves the logging configuration docs to recommend specific instructions for how to configure logs for posting to issues. Signed-off-by: Andrew Thornton * Update docs/content/doc/advanced/logging-documentation.en-us.md --- doc/advanced/logging-documentation.en-us.md | 43 ++++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/doc/advanced/logging-documentation.en-us.md b/doc/advanced/logging-documentation.en-us.md index 0b3b018f..7e0f8543 100644 --- a/doc/advanced/logging-documentation.en-us.md +++ b/doc/advanced/logging-documentation.en-us.md @@ -290,9 +290,48 @@ messages. However, you could perhaps set this logger to work on `FATAL`. * `RECEIVERS`: Email addresses to send to. * `SUBJECT`: **Diagnostic message from Gitea** -## Default Configuration +## Debugging problems -The default empty configuration is equivalent to: +When submitting logs in Gitea issues it is often helpful to submit +merged logs obtained by either by redirecting the console log to a file or +copying and pasting it. To that end it is recommended to set your logging to: + +```ini +[database] +LOG_SQL = false ; SQL logs are rarely helpful unless we specifically ask for them + +... + +[log] +MODE = console +LEVEL = debug ; please set the level to debug when we are debugging a problem +REDIRECT_MACARON_LOG = true +MACARON = console +ROUTER = console +COLORIZE = false ; this can be true if you can strip out the ansi coloring +``` + +Sometimes it will be helpful get some specific `TRACE` level logging retricted +to messages that match a specific `EXPRESSION`. Adjusting the `MODE` in the +`[log]` section to `MODE = console,traceconsole` to add a new logger output +`traceconsole` and then adding its corresponding section would be helpful: + +```ini +[log.traceconsole] ; traceconsole here is just a name +MODE = console ; this is the output that the traceconsole writes to +LEVEL = trace +EXPRESSION = ; putting a string here will restrict this logger to logging only those messages that match this expression +``` + +(It's worth noting that log messages that match the expression at or above debug +level will get logged twice so don't worry about that.) + +`STACKTRACE_LEVEL` should generally be left unconfigured (and hence kept at +`none`). There are only very specific occasions when it useful. + +## Empty Configuration + +The empty configuration is equivalent to: ```ini [log]