1 files changed, 41 insertions, 2 deletions
diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md
index 0b3b018fab..7e0f85430b 100644
--- a/docs/content/doc/advanced/logging-documentation.en-us.md
+++ b/docs/content/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]