You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
My pull request changes the logging documentation that is visible here:
https://docs.gitea.io/en-us/logging-configuration/
The reason behind the changes is that for some time I've found the
logging documentation confusing, and wanted to give a try at making it
more clear.
---
If you find the existing changes to be ok, please don't merge yet, as I
have further ideas which I want to discuss with you before making the
changes.
### Swap the "Log Groups" and "Log outputs" sections.
I want to move the "Log outputs" section before the "Log Groups"
section. The reason is that the "Log Groups" section refers to ini
sections that are only later explained, and to concepts that are general
and should be documented in "Log outputs" or a different section.
This change is essentially a swap of the "Log Groups" and "Log outputs"
sections. That way the doumentation would follow the structure in which
the ini file is built: first explaining the outer sections, and then the
inner ones ([log], [log.name], [log.name.default], ...)
### Explain the workings of ambigous settings below the settings listing
Right now the basics of a setting is shown later than the explanation of
its special workings, for example with `FILE_NAME` at [the file output
mode](https://docs.gitea.io/en-us/logging-configuration/#file-mode)
(well, if the first changes are taken into account).
Currently I have `TODO` witten at 2 settings, which I have to figure out
how do they exactly work before I can document them.
### New section about [log]
New section after "Collecting Logs for Help" about how the top level
[log] itself works and what can go there.
Currently, variables that directly go into [log] are noted throughout
the whole document.
---
Please let me know what you think about the changes.
A counterargument that I myself see is that some of this is already
present in the cheatsheet, but I think it would be better to have [this
document](https://docs.gitea.io/en-us/logging-configuration/) as a
throrough explanation of how logging is configured, and the cheatsheet
would only have a short outline of the possible sections and variables.
Co-authored-by: Lunny Xiao <[email protected]>
Copy file name to clipboardExpand all lines: docs/content/doc/advanced/logging-documentation.en-us.md
+168-100
Original file line number
Diff line number
Diff line change
@@ -15,6 +15,14 @@ menu:
15
15
16
16
# Logging Configuration
17
17
18
+
The logging configuration of Gitea mainly consists of 3 types of components:
19
+
20
+
- The `[log]` section for general configuration
21
+
-`[log.<sublogger>]` sections for the configuration of different log outputs
22
+
-`[log.<sublogger>.<group>]` sections for output specific configuration of a log group
23
+
24
+
As mentioned below, there is a fully functional log output by default, so it is not necessary to define one.
25
+
18
26
**Table of Contents**
19
27
20
28
{{< toc >}}
@@ -23,6 +31,166 @@ menu:
23
31
24
32
To collect logs for help and issue report, see [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}).
25
33
34
+
## The `[log]` section
35
+
36
+
Configuration of logging facilities in Gitea happen in the `[log]` section and it's subsections.
37
+
38
+
In the top level `[log]` section the following configurations can be placed:
39
+
40
+
-`ROOT_PATH`: (Default: **%(GITEA_WORK_DIR)/log**): Base path for log files
41
+
-`MODE`: (Default: **console**) List of log outputs to use for the Default logger.
42
+
-`ROUTER`: (Default: **console**): List of log outputs to use for the Router logger.
43
+
-`ACCESS`: List of log outputs to use for the Access logger.
44
+
-`XORM`: (Default: **,**) List of log outputs to use for the XORM logger.
45
+
-`ENABLE_ACCESS_LOG`: (Default: **false**): whether the Access logger is allowed to emit logs
46
+
-`ENABLE_XORM_LOG`: (Default: **true**): whether the XORM logger is allowed to emit logs
47
+
48
+
For details on the loggers check the "Log Groups" section.
49
+
Important: log outputs won't be used if you don't enable them for the desired loggers in the corresponding list value.
50
+
51
+
Lists are specified as comma separated values. This format also works in subsection.
52
+
53
+
This section may be used for defining default values for subsections.
54
+
Examples:
55
+
56
+
-`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).
57
+
-`STACKTRACE_LEVEL`: (Default: **None**) For this and more severe events the stacktrace will be printed upon getting logged.
58
+
59
+
Some values are not inherited by subsections. For details see the "Non-inherited default values" section.
60
+
61
+
## Log outputs
62
+
63
+
Log outputs are the targets to which log messages will be sent.
64
+
The content and the format of the log messages to be saved can be configured in these.
65
+
66
+
Log outputs are also called subloggers.
67
+
68
+
Gitea provides 4 possible log outputs:
69
+
70
+
-`console` - Log to `os.Stdout` or `os.Stderr`
71
+
-`file` - Log to a file
72
+
-`conn` - Log to a socket (network or unix)
73
+
-`smtp` - Log via email
74
+
75
+
By default, Gitea has a `console` output configured, which is used by the loggers as seen in the section "The log section" above.
76
+
77
+
### Common configuration
78
+
79
+
Certain configuration is common to all modes of log output:
80
+
81
+
-`MODE` is the mode of the log output. It will default to the sublogger
82
+
name, thus `[log.console.router]` will default to `MODE = console`.
83
+
For mode specific confgurations read further.
84
+
-`LEVEL` is the lowest level that this output will log. This value
85
+
is inherited from `[log]` and in the case of the non-default loggers
86
+
from `[log.sublogger]`.
87
+
-`STACKTRACE_LEVEL` is the lowest level that this output will print
88
+
a stacktrace. This value is inherited.
89
+
-`COLORIZE` will default to `true` for `console` as
90
+
described, otherwise it will default to `false`.
91
+
92
+
### Non-inherited default values
93
+
94
+
There are several values which are not inherited as described above but
95
+
rather default to those specific to type of logger, these are:
96
+
`EXPRESSION`, `FLAGS`, `PREFIX` and `FILE_NAME`.
97
+
98
+
#### `EXPRESSION`
99
+
100
+
`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.
101
+
102
+
Please note this expression will be run in the sublogger's goroutine
103
+
not the logging event subroutine. Therefore it can be complicated.
104
+
105
+
#### `FLAGS`
106
+
107
+
`FLAGS` represents the preceding logging context information that is
108
+
printed before each message. It is a comma-separated string set. The order of values does not matter.
109
+
110
+
Possible values are:
111
+
112
+
-`none` or `,` - No flags.
113
+
-`date` - the date in the local time zone: `2009/01/23`.
114
+
-`time` - the time in the local time zone: `01:23:23`.
-`longfile` - full file name and line number: `/a/b/c/d.go:23`.
118
+
-`shortfile` - final file name element and line number: `d.go:23`.
119
+
-`funcname` - function name of the caller: `runtime.Caller()`.
120
+
-`shortfuncname` - last part of the function name. Overrides
121
+
`funcname`.
122
+
-`utc` - if date or time is set, use UTC rather than the local time
123
+
zone.
124
+
-`levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info.
125
+
-`level` - Provided level in brackets `[INFO]`
126
+
-`medfile` - Last 20 characters of the filename - equivalent to
127
+
`shortfile,longfile`.
128
+
-`stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial`
129
+
130
+
### Console mode
131
+
132
+
In this mode the logger will forward log messages to the stdout and
133
+
stderr streams attached to the Gitea process.
134
+
135
+
For loggers in console mode, `COLORIZE` will default to `true` if not
136
+
on windows, or the windows terminal can be set into ANSI mode or is a
137
+
cygwin or Msys pipe.
138
+
139
+
Settings:
140
+
141
+
-`STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.
142
+
143
+
### File mode
144
+
145
+
In this mode the logger will save log messages to a file.
146
+
147
+
Settings:
148
+
149
+
-`FILE_NAME`: The file to write the log events to. For details see below.
150
+
-`MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see below.
151
+
-`LOG_ROTATE`**true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?.
152
+
-`DAILY_ROTATE`: **true**: Whether to rotate logs daily.
153
+
-`MAX_DAYS`: **7**: Delete rotated log files after this number of days.
154
+
-`COMPRESS`: **true**: Whether to compress old log files by default with gzip.
155
+
-`COMPRESSION_LEVEL`: **-1**: Compression level. For details see below.
156
+
157
+
The default value of `FILE_NAME` depends on the respective logger facility.
158
+
If unset, their own default will be used.
159
+
If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section.
160
+
161
+
`MAX_SIZE_SHIFT` defines the maximum size of a file by left shifting 1 the given number of times (`1 << x`).
162
+
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).
163
+
164
+
The useful values of `COMPRESSION_LEVEL` are from 1 to (and including) 9, where higher numbers mean better compression.
165
+
Beware that better compression might come with higher resource usage.
166
+
Must be preceded with a `-` sign.
167
+
168
+
### Conn mode
169
+
170
+
In this mode the logger will send log messages over a network socket.
171
+
172
+
Settings:
173
+
174
+
-`ADDR`: **:7020**: Sets the address to connect to.
175
+
-`PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
176
+
-`RECONNECT`: **false**: Try to reconnect when connection is lost.
177
+
-`RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
178
+
179
+
### SMTP mode
180
+
181
+
In this mode the logger will send log messages in email.
182
+
183
+
It is not recommended to use this logger to send general logging
184
+
messages. However, you could perhaps set this logger to work on `FATAL` messages only.
185
+
186
+
Settings:
187
+
188
+
-`HOST`: **127.0.0.1:25**: The SMTP host to connect to.
189
+
-`USER`: User email address to send from.
190
+
-`PASSWD`: Password for the smtp server.
191
+
-`RECEIVERS`: Email addresses to send to.
192
+
-`SUBJECT`: **Diagnostic message from Gitea**. The content of the email's subject field.
193
+
26
194
## Log Groups
27
195
28
196
The fundamental thing to be aware of in Gitea is that there are several
@@ -172,106 +340,6 @@ which will not be inherited from the `[log]` or relevant
172
340
-`EXPRESSION` will default to `""`
173
341
-`PREFIX` will default to `""`
174
342
175
-
## Log outputs
176
-
177
-
Gitea provides 4 possible log outputs:
178
-
179
-
-`console` - Log to `os.Stdout` or `os.Stderr`
180
-
-`file` - Log to a file
181
-
-`conn` - Log to a keep-alive TCP connection
182
-
-`smtp` - Log via email
183
-
184
-
Certain configuration is common to all modes of log output:
185
-
186
-
-`LEVEL` is the lowest level that this output will log. This value
187
-
is inherited from `[log]` and in the case of the non-default loggers
188
-
from `[log.sublogger]`.
189
-
-`STACKTRACE_LEVEL` is the lowest level that this output will print
190
-
a stacktrace. This value is inherited.
191
-
-`MODE` is the mode of the log output. It will default to the sublogger
192
-
name. Thus `[log.console.router]` will default to `MODE = console`.
193
-
-`COLORIZE` will default to `true` for `console` as
194
-
described, otherwise it will default to `false`.
195
-
196
-
### Non-inherited default values
197
-
198
-
There are several values which are not inherited as described above but
199
-
rather default to those specific to type of logger, these are:
200
-
`EXPRESSION`, `FLAGS`, `PREFIX` and `FILE_NAME`.
201
-
202
-
#### `EXPRESSION`
203
-
204
-
`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.
205
-
206
-
Please note this expression will be run in the sublogger's goroutine
207
-
not the logging event subroutine. Therefore it can be complicated.
208
-
209
-
#### `FLAGS`
210
-
211
-
`FLAGS` represents the preceding logging context information that is
212
-
printed before each message. It is a comma-separated string set. The order of values does not matter.
213
-
214
-
Possible values are:
215
-
216
-
-`none` or `,` - No flags.
217
-
-`date` - the date in the local time zone: `2009/01/23`.
218
-
-`time` - the time in the local time zone: `01:23:23`.
0 commit comments