From 22ba9d49ea212821d6be5ff6641846fa08b147c2 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Wed, 2 Nov 2022 13:33:22 +0100 Subject: [PATCH 1/8] description for logger outputs, fix mistake extend documentation of logger outputs with short description (what do they do), and fix mistake in the brief listing --- .../advanced/logging-documentation.en-us.md | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 4e8cbb32825d0..f66949ed07510 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -174,13 +174,20 @@ which will not be inherited from the `[log]` or relevant ## Log outputs +Log outputs are the targets to which log messages will be sent. +The content and the format of the log messages to be saved can be configured in these. + +Log outputs are also called subloggers. + Gitea provides 4 possible log outputs: - `console` - Log to `os.Stdout` or `os.Stderr` - `file` - Log to a file -- `conn` - Log to a keep-alive TCP connection +- `conn` - Log to a socket (network or unix) - `smtp` - Log via email +### Common configuration + Certain configuration is common to all modes of log output: - `LEVEL` is the lowest level that this output will log. This value @@ -233,6 +240,9 @@ Possible values are: ### Console mode +In this mode the logger will forward log messages to the stdout and +stderr streams attached to the Gitea process. + For loggers in console mode, `COLORIZE` will default to `true` if not on windows, or the windows terminal can be set into ANSI mode or is a cygwin or Msys pipe. @@ -242,8 +252,11 @@ If `STDERR` is set to `true` the logger will use `os.Stderr` instead of ### File mode -The `FILE_NAME` defaults as described above. If set it will be relative -to the provided `ROOT_PATH` in the master `[log]` section. +In this mode the logger will save log messages to a file. + +The `FILE_NAME` defaults as described in the respective logger facilities. +If unset, their own default will be used. +If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. Other values: @@ -256,6 +269,8 @@ Other values: ### Conn mode +In this mode the logger will send log messages over a network socket. + - `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. - `RECONNECT`: **false**: Try to reconnect when connection is lost. - `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". @@ -263,6 +278,8 @@ Other values: ### SMTP mode +In this mode the logger will send log messages in email. + It is not recommended to use this logger to send general logging messages. However, you could perhaps set this logger to work on `FATAL`. From f4cf4fe0c724f52e328bb7dd9d8740087eee6e70 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Wed, 2 Nov 2022 18:14:40 +0100 Subject: [PATCH 2/8] reorder lines of sublogger settings, always explicitly mention all config values. The new order of the settings moves those to earlier places that have a higher impact over the functionality of the logger --- .../advanced/logging-documentation.en-us.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index f66949ed07510..31e67c809a3af 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -190,13 +190,14 @@ Gitea provides 4 possible log outputs: Certain configuration is common to all modes of log output: +- `MODE` is the mode of the log output. It will default to the sublogger + name, thus `[log.console.router]` will default to `MODE = console`. + For mode specific confgurations read further. - `LEVEL` is the lowest level that this output will log. This value is inherited from `[log]` and in the case of the non-default loggers from `[log.sublogger]`. - `STACKTRACE_LEVEL` is the lowest level that this output will print a stacktrace. This value is inherited. -- `MODE` is the mode of the log output. It will default to the sublogger - name. Thus `[log.console.router]` will default to `MODE = console`. - `COLORIZE` will default to `true` for `console` as described, otherwise it will default to `false`. @@ -247,8 +248,8 @@ For loggers in console mode, `COLORIZE` will default to `true` if not on windows, or the windows terminal can be set into ANSI mode or is a cygwin or Msys pipe. -If `STDERR` is set to `true` the logger will use `os.Stderr` instead of -`os.Stdout`. +Settings: +- `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.| ### File mode @@ -258,10 +259,10 @@ The `FILE_NAME` defaults as described in the respective logger facilities. If unset, their own default will be used. If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. -Other values: - -- `LOG_ROTATE`: **true**: Rotate the log files. +Settings: +- `FILE_NAME`: The file to write the log events to. For details see above. - `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb. +- `LOG_ROTATE`: **true**: Rotate the log files. - `DAILY_ROTATE`: **true**: Rotate logs daily. - `MAX_DAYS`: **7**: Delete the log file after n days - `COMPRESS`: **true**: Compress old log files by default with gzip @@ -271,21 +272,23 @@ Other values: In this mode the logger will send log messages over a network socket. -- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. -- `RECONNECT`: **false**: Try to reconnect when connection is lost. -- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". +Settings: - `ADDR`: **:7020**: Sets the address to connect to. +- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". +- `RECONNECT`: **false**: Try to reconnect when connection is lost. +- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. ### SMTP mode In this mode the logger will send log messages in email. It is not recommended to use this logger to send general logging -messages. However, you could perhaps set this logger to work on `FATAL`. +messages. However, you could perhaps set this logger to work on `FATAL` messages only. +Settings: +- `HOST`: **127.0.0.1:25**: The SMTP host to connect to. - `USER`: User email address to send from. - `PASSWD`: Password for the smtp server. -- `HOST`: **127.0.0.1:25**: The SMTP host to connect to. - `RECEIVERS`: Email addresses to send to. - `SUBJECT`: **Diagnostic message from Gitea** From 5fe6466f6e8b52c75b228b6fc7c913f795de6fa0 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Wed, 2 Nov 2022 18:34:44 +0100 Subject: [PATCH 3/8] clarify description of output config values --- .../doc/advanced/logging-documentation.en-us.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 31e67c809a3af..4680f76a34a02 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -249,7 +249,7 @@ on windows, or the windows terminal can be set into ANSI mode or is a cygwin or Msys pipe. Settings: -- `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.| +- `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`. ### File mode @@ -261,12 +261,12 @@ If set it will be relative to the provided `ROOT_PATH` in the master `[log]` sec Settings: - `FILE_NAME`: The file to write the log events to. For details see above. -- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb. -- `LOG_ROTATE`: **true**: Rotate the log files. -- `DAILY_ROTATE`: **true**: Rotate logs daily. -- `MAX_DAYS`: **7**: Delete the log file after n days -- `COMPRESS`: **true**: Compress old log files by default with gzip -- `COMPRESSION_LEVEL`: **-1**: Compression level +- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see here: TODO. +- `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?. +- `DAILY_ROTATE`: **true**: Whether to rotate logs daily. +- `MAX_DAYS`: **7**: Delete rotated log files after this number of days. +- `COMPRESS`: **true**: Whether to compress old log files by default with gzip. +- `COMPRESSION_LEVEL`: **-1**: Compression level. ### Conn mode @@ -290,7 +290,7 @@ Settings: - `USER`: User email address to send from. - `PASSWD`: Password for the smtp server. - `RECEIVERS`: Email addresses to send to. -- `SUBJECT`: **Diagnostic message from Gitea** +- `SUBJECT`: **Diagnostic message from Gitea**. The content of the email's subject field. ## Debugging problems From 84283c59b211eed3edfdb24a47680d27bc64cbd5 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Mon, 7 Nov 2022 19:48:35 +0100 Subject: [PATCH 4/8] fix markdownlint issues --- docs/content/doc/advanced/logging-documentation.en-us.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 4680f76a34a02..25fa65ab2096c 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -249,6 +249,7 @@ on windows, or the windows terminal can be set into ANSI mode or is a cygwin or Msys pipe. Settings: + - `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`. ### File mode @@ -260,6 +261,7 @@ If unset, their own default will be used. If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. Settings: + - `FILE_NAME`: The file to write the log events to. For details see above. - `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see here: TODO. - `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?. @@ -273,6 +275,7 @@ Settings: In this mode the logger will send log messages over a network socket. Settings: + - `ADDR`: **:7020**: Sets the address to connect to. - `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". - `RECONNECT`: **false**: Try to reconnect when connection is lost. @@ -286,6 +289,7 @@ It is not recommended to use this logger to send general logging messages. However, you could perhaps set this logger to work on `FATAL` messages only. Settings: + - `HOST`: **127.0.0.1:25**: The SMTP host to connect to. - `USER`: User email address to send from. - `PASSWD`: Password for the smtp server. From aeb4b993cb1d154989d1164dc6710ac220a4c4af Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Mon, 7 Nov 2022 19:58:45 +0100 Subject: [PATCH 5/8] swap "Log Groups" and "Log outputs" sections --- .../advanced/logging-documentation.en-us.md | 248 +++++++++--------- 1 file changed, 124 insertions(+), 124 deletions(-) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 25fa65ab2096c..acad9fa2d989b 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -23,6 +23,130 @@ menu: To collect logs for help and issue report, see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}). +## Log outputs + +Log outputs are the targets to which log messages will be sent. +The content and the format of the log messages to be saved can be configured in these. + +Log outputs are also called subloggers. + +Gitea provides 4 possible log outputs: + +- `console` - Log to `os.Stdout` or `os.Stderr` +- `file` - Log to a file +- `conn` - Log to a socket (network or unix) +- `smtp` - Log via email + +### Common configuration + +Certain configuration is common to all modes of log output: + +- `MODE` is the mode of the log output. It will default to the sublogger + name, thus `[log.console.router]` will default to `MODE = console`. + For mode specific confgurations read further. +- `LEVEL` is the lowest level that this output will log. This value + is inherited from `[log]` and in the case of the non-default loggers + from `[log.sublogger]`. +- `STACKTRACE_LEVEL` is the lowest level that this output will print + a stacktrace. This value is inherited. +- `COLORIZE` will default to `true` for `console` as + described, otherwise it will default to `false`. + +### Non-inherited default values + +There are several values which are not inherited as described above but +rather default to those specific to type of logger, these are: +`EXPRESSION`, `FLAGS`, `PREFIX` and `FILE_NAME`. + +#### `EXPRESSION` + +`EXPRESSION` represents a regular expression that log events must match to be logged by the sublogger. Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match. NB: the whole message or string doesn't need to completely match. + +Please note this expression will be run in the sublogger's goroutine +not the logging event subroutine. Therefore it can be complicated. + +#### `FLAGS` + +`FLAGS` represents the preceding logging context information that is +printed before each message. It is a comma-separated string set. The order of values does not matter. + +Possible values are: + +- `none` or `,` - No flags. +- `date` - the date in the local time zone: `2009/01/23`. +- `time` - the time in the local time zone: `01:23:23`. +- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes + time. +- `longfile` - full file name and line number: `/a/b/c/d.go:23`. +- `shortfile` - final file name element and line number: `d.go:23`. +- `funcname` - function name of the caller: `runtime.Caller()`. +- `shortfuncname` - last part of the function name. Overrides + `funcname`. +- `utc` - if date or time is set, use UTC rather than the local time + zone. +- `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info. +- `level` - Provided level in brackets `[INFO]` +- `medfile` - Last 20 characters of the filename - equivalent to + `shortfile,longfile`. +- `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial` + +### Console mode + +In this mode the logger will forward log messages to the stdout and +stderr streams attached to the Gitea process. + +For loggers in console mode, `COLORIZE` will default to `true` if not +on windows, or the windows terminal can be set into ANSI mode or is a +cygwin or Msys pipe. + +Settings: + +- `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`. + +### File mode + +In this mode the logger will save log messages to a file. + +The `FILE_NAME` defaults as described in the respective logger facilities. +If unset, their own default will be used. +If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. + +Settings: + +- `FILE_NAME`: The file to write the log events to. For details see above. +- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see here: TODO. +- `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?. +- `DAILY_ROTATE`: **true**: Whether to rotate logs daily. +- `MAX_DAYS`: **7**: Delete rotated log files after this number of days. +- `COMPRESS`: **true**: Whether to compress old log files by default with gzip. +- `COMPRESSION_LEVEL`: **-1**: Compression level. + +### Conn mode + +In this mode the logger will send log messages over a network socket. + +Settings: + +- `ADDR`: **:7020**: Sets the address to connect to. +- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". +- `RECONNECT`: **false**: Try to reconnect when connection is lost. +- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. + +### SMTP mode + +In this mode the logger will send log messages in email. + +It is not recommended to use this logger to send general logging +messages. However, you could perhaps set this logger to work on `FATAL` messages only. + +Settings: + +- `HOST`: **127.0.0.1:25**: The SMTP host to connect to. +- `USER`: User email address to send from. +- `PASSWD`: Password for the smtp server. +- `RECEIVERS`: Email addresses to send to. +- `SUBJECT`: **Diagnostic message from Gitea**. The content of the email's subject field. + ## Log Groups The fundamental thing to be aware of in Gitea is that there are several @@ -172,130 +296,6 @@ which will not be inherited from the `[log]` or relevant - `EXPRESSION` will default to `""` - `PREFIX` will default to `""` -## Log outputs - -Log outputs are the targets to which log messages will be sent. -The content and the format of the log messages to be saved can be configured in these. - -Log outputs are also called subloggers. - -Gitea provides 4 possible log outputs: - -- `console` - Log to `os.Stdout` or `os.Stderr` -- `file` - Log to a file -- `conn` - Log to a socket (network or unix) -- `smtp` - Log via email - -### Common configuration - -Certain configuration is common to all modes of log output: - -- `MODE` is the mode of the log output. It will default to the sublogger - name, thus `[log.console.router]` will default to `MODE = console`. - For mode specific confgurations read further. -- `LEVEL` is the lowest level that this output will log. This value - is inherited from `[log]` and in the case of the non-default loggers - from `[log.sublogger]`. -- `STACKTRACE_LEVEL` is the lowest level that this output will print - a stacktrace. This value is inherited. -- `COLORIZE` will default to `true` for `console` as - described, otherwise it will default to `false`. - -### Non-inherited default values - -There are several values which are not inherited as described above but -rather default to those specific to type of logger, these are: -`EXPRESSION`, `FLAGS`, `PREFIX` and `FILE_NAME`. - -#### `EXPRESSION` - -`EXPRESSION` represents a regular expression that log events must match to be logged by the sublogger. Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match. NB: the whole message or string doesn't need to completely match. - -Please note this expression will be run in the sublogger's goroutine -not the logging event subroutine. Therefore it can be complicated. - -#### `FLAGS` - -`FLAGS` represents the preceding logging context information that is -printed before each message. It is a comma-separated string set. The order of values does not matter. - -Possible values are: - -- `none` or `,` - No flags. -- `date` - the date in the local time zone: `2009/01/23`. -- `time` - the time in the local time zone: `01:23:23`. -- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes - time. -- `longfile` - full file name and line number: `/a/b/c/d.go:23`. -- `shortfile` - final file name element and line number: `d.go:23`. -- `funcname` - function name of the caller: `runtime.Caller()`. -- `shortfuncname` - last part of the function name. Overrides - `funcname`. -- `utc` - if date or time is set, use UTC rather than the local time - zone. -- `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info. -- `level` - Provided level in brackets `[INFO]` -- `medfile` - Last 20 characters of the filename - equivalent to - `shortfile,longfile`. -- `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial` - -### Console mode - -In this mode the logger will forward log messages to the stdout and -stderr streams attached to the Gitea process. - -For loggers in console mode, `COLORIZE` will default to `true` if not -on windows, or the windows terminal can be set into ANSI mode or is a -cygwin or Msys pipe. - -Settings: - -- `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`. - -### File mode - -In this mode the logger will save log messages to a file. - -The `FILE_NAME` defaults as described in the respective logger facilities. -If unset, their own default will be used. -If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. - -Settings: - -- `FILE_NAME`: The file to write the log events to. For details see above. -- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see here: TODO. -- `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?. -- `DAILY_ROTATE`: **true**: Whether to rotate logs daily. -- `MAX_DAYS`: **7**: Delete rotated log files after this number of days. -- `COMPRESS`: **true**: Whether to compress old log files by default with gzip. -- `COMPRESSION_LEVEL`: **-1**: Compression level. - -### Conn mode - -In this mode the logger will send log messages over a network socket. - -Settings: - -- `ADDR`: **:7020**: Sets the address to connect to. -- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp". -- `RECONNECT`: **false**: Try to reconnect when connection is lost. -- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message. - -### SMTP mode - -In this mode the logger will send log messages in email. - -It is not recommended to use this logger to send general logging -messages. However, you could perhaps set this logger to work on `FATAL` messages only. - -Settings: - -- `HOST`: **127.0.0.1:25**: The SMTP host to connect to. -- `USER`: User email address to send from. -- `PASSWD`: Password for the smtp server. -- `RECEIVERS`: Email addresses to send to. -- `SUBJECT`: **Diagnostic message from Gitea**. The content of the email's subject field. - ## Debugging problems When submitting logs in Gitea issues it is often helpful to submit From 33d04384f4730fd8a7188b89197e7cd3cff1c6b7 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Mon, 7 Nov 2022 21:49:57 +0100 Subject: [PATCH 6/8] Add new section: The `[log]` section Details the usage of the main [log] section, and the default values it uses. --- .../advanced/logging-documentation.en-us.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index acad9fa2d989b..24217c5cfbee6 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -23,6 +23,33 @@ menu: To collect logs for help and issue report, see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}). +## The `[log]` section + +Configuration of logging facilities in Gitea happen in the `[log]` section and it's subsections. + +In the top level `[log]` section the following configurations can be placed: + +- `ROOT_PATH`: (Default: **%(GITEA_WORK_DIR)/log**): Base path for log files +- `MODE`: (Default: **console**) List of log outputs to use for the Default logger. +- `ROUTER`: (Default: **console**): List of log outputs to use for the Router logger. +- `ACCESS`: List of log outputs to use for the Access logger. +- `XORM`: (Default: **,**) List of log outputs to use for the XORM logger. +- `ENABLE_ACCESS_LOG`: (Default: **false**): whether the Access logger is allowed to emit logs +- `ENABLE_XORM_LOG`: (Default: **true**): whether the XORM logger is allowed to emit logs + +For details on the loggers check the "Log Groups" section. +Important: log outputs won't be used if you don't enable them for the desired loggers in the corresponding list value. + +Lists are specified as comma separated values. This format also works in subsection. + +This section may be used for defining default values for subsections. +Examples: + +- `LEVEL`: (Default: **Info**) Least severe log events to persist. Case insensitive. The full list of levels as of v1.17.3 can be read [here](https://github.com/go-gitea/gitea/blob/v1.17.3/custom/conf/app.example.ini#L507). +- `STACKTRACE_LEVEL`: (Default: **None**) For this and more severe events the stacktrace will be printed upon getting logged. + +Some values are not inherited by subsections. For details see the "Non-inherited default values" section. + ## Log outputs Log outputs are the targets to which log messages will be sent. From f91101d41ad65ff3f3644e6442e653bf55e41532 Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Mon, 7 Nov 2022 21:52:22 +0100 Subject: [PATCH 7/8] Add introduction to H1 Outlines how the logging configuration is built up --- .../doc/advanced/logging-documentation.en-us.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index 24217c5cfbee6..e0d677ab28b91 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -15,6 +15,14 @@ menu: # Logging Configuration +The logging configuration of Gitea mainly consists of 3 types of components: + +- The `[log]` section for general configuration +- `[log.]` sections for the configuration of different log outputs +- `[log..]` sections for output specific configuration of a log group + +As mentioned below, there is a fully functional log output by default, so it is not necessary to define one. + **Table of Contents** {{< toc >}} @@ -64,6 +72,8 @@ Gitea provides 4 possible log outputs: - `conn` - Log to a socket (network or unix) - `smtp` - Log via email +By default, Gitea has a `console` output configured, which is used by the loggers as seen in the section "The log section" above. + ### Common configuration Certain configuration is common to all modes of log output: From 1f92b2aba54bfa480d85ce16dc4a377d19a2574a Mon Sep 17 00:00:00 2001 From: mpeter50 <83356418+mpeter50@users.noreply.github.com> Date: Mon, 7 Nov 2022 22:21:06 +0100 Subject: [PATCH 8/8] Move configuration explanations below the list for File mode. Extend explanations. --- .../advanced/logging-documentation.en-us.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/content/doc/advanced/logging-documentation.en-us.md b/docs/content/doc/advanced/logging-documentation.en-us.md index e0d677ab28b91..145c8c320c78d 100644 --- a/docs/content/doc/advanced/logging-documentation.en-us.md +++ b/docs/content/doc/advanced/logging-documentation.en-us.md @@ -144,19 +144,26 @@ Settings: In this mode the logger will save log messages to a file. -The `FILE_NAME` defaults as described in the respective logger facilities. -If unset, their own default will be used. -If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. - Settings: -- `FILE_NAME`: The file to write the log events to. For details see above. -- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see here: TODO. +- `FILE_NAME`: The file to write the log events to. For details see below. +- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see below. - `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?. - `DAILY_ROTATE`: **true**: Whether to rotate logs daily. - `MAX_DAYS`: **7**: Delete rotated log files after this number of days. - `COMPRESS`: **true**: Whether to compress old log files by default with gzip. -- `COMPRESSION_LEVEL`: **-1**: Compression level. +- `COMPRESSION_LEVEL`: **-1**: Compression level. For details see below. + +The default value of `FILE_NAME` depends on the respective logger facility. +If unset, their own default will be used. +If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section. + +`MAX_SIZE_SHIFT` defines the maximum size of a file by left shifting 1 the given number of times (`1 << x`). +The exact behavior at the time of v1.17.3 can be seen [here](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185). + +The useful values of `COMPRESSION_LEVEL` are from 1 to (and including) 9, where higher numbers mean better compression. +Beware that better compression might come with higher resource usage. +Must be preceded with a `-` sign. ### Conn mode