From d65cd5677af3df5d616bf48dfd4be354e23c184f Mon Sep 17 00:00:00 2001
From: zeripath <art27@cantab.net>
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 <art27@cantab.net>

* Update docs/content/doc/advanced/logging-documentation.en-us.md
---
 docker/root/etc/templates/app.ini             |  6 +++
 .../advanced/logging-documentation.en-us.md   | 43 ++++++++++++++++++-
 routers/install.go                            |  6 ++-
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/docker/root/etc/templates/app.ini b/docker/root/etc/templates/app.ini
index 9b23c1270..1a831a6d1 100644
--- a/docker/root/etc/templates/app.ini
+++ b/docker/root/etc/templates/app.ini
@@ -29,6 +29,7 @@ HOST    = $DB_HOST
 NAME    = $DB_NAME
 USER    = $DB_USER
 PASSWD  = $DB_PASSWD
+LOG_SQL = false
 
 [indexer]
 ISSUE_INDEXER_PATH = /data/gitea/indexers/issues.bleve
@@ -44,6 +45,11 @@ REPOSITORY_AVATAR_UPLOAD_PATH = /data/gitea/repo-avatars
 PATH = /data/gitea/attachments
 
 [log]
+MODE = console
+LEVEL = info
+REDIRECT_MACARON_LOG = true
+MACARON = console
+ROUTER = console
 ROOT_PATH = /data/gitea/log
 
 [security]
diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md
index 0b3b018fa..7e0f85430 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]
diff --git a/routers/install.go b/routers/install.go
index 028b5d3ee..a136cf44b 100644
--- a/routers/install.go
+++ b/routers/install.go
@@ -271,6 +271,7 @@ func InstallPost(ctx *context.Context, form auth.InstallForm) {
 	cfg.Section("database").Key("SSL_MODE").SetValue(setting.Database.SSLMode)
 	cfg.Section("database").Key("CHARSET").SetValue(setting.Database.Charset)
 	cfg.Section("database").Key("PATH").SetValue(setting.Database.Path)
+	cfg.Section("database").Key("LOG_SQL").SetValue("false") // LOG_SQL is rarely helpful
 
 	cfg.Section("").Key("APP_NAME").SetValue(form.AppName)
 	cfg.Section("repository").Key("ROOT").SetValue(form.RepoRootPath)
@@ -330,9 +331,12 @@ func InstallPost(ctx *context.Context, form auth.InstallForm) {
 
 	cfg.Section("session").Key("PROVIDER").SetValue("file")
 
-	cfg.Section("log").Key("MODE").SetValue("file")
+	cfg.Section("log").Key("MODE").SetValue("console")
 	cfg.Section("log").Key("LEVEL").SetValue(setting.LogLevel)
 	cfg.Section("log").Key("ROOT_PATH").SetValue(form.LogRootPath)
+	cfg.Section("log").Key("REDIRECT_MACARON_LOG").SetValue("true")
+	cfg.Section("log").Key("MACARON").SetValue("console")
+	cfg.Section("log").Key("ROUTER").SetValue("console")
 
 	cfg.Section("security").Key("INSTALL_LOCK").SetValue("true")
 	var secretKey string