From e5d23d8676b72e9b2df669b5c16628f69ecc8bc2 Mon Sep 17 00:00:00 2001 From: Aurelien DARRAGON Date: Mon, 25 Sep 2023 16:10:02 +0200 Subject: [PATCH] DOC: config: unify "log" directive doc "log" directive description was found 2 times in the configuration file: First, in 3.1 in the "global parameters" chapter, and then in 4.2 in the per-proxy keyword options. Both descriptions are almost identical: having to maintain the "same" documentation in 2 different places is error-prone. Due to this, some precisions have been added in one of them, and were missing from the other, and vice-versa, probably because one didn't see that the "log" directive was also documented elsewhere. To prevent the 2 descriptions from further diverging, and make it easier to maintain, we merge them in the per-proxy "log" directive description (in 4.2 chapter), and we add a pointer to it in the global "log" to encourage the user to refer to the per-proxy "log" documentation for usage details. --- doc/configuration.txt | 134 +----------------------------------------- 1 file changed, 3 insertions(+), 131 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index dd78f4542..52cec0efe 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -1840,137 +1840,7 @@ log
[len ] [format ] [sample :] [max level [min level]] Adds a global syslog server. Several global servers can be defined. They will receive logs for starts and exits, as well as all logs from proxies - configured with "log global". - -
can be one of: - - - An IPv4 address optionally followed by a colon and a UDP port. If - no port is specified, 514 is used by default (the standard syslog - port). - - - An IPv6 address followed by a colon and optionally a UDP port. If - no port is specified, 514 is used by default (the standard syslog - port). - - - A filesystem path to a datagram UNIX domain socket, keeping in mind - considerations for chroot (be sure the path is accessible inside - the chroot) and uid/gid (be sure the path is appropriately - writable). - - - A file descriptor number in the form "fd@", which may point - to a pipe, terminal, or socket. In this case unbuffered logs are used - and one writev() call per log is performed. This is a bit expensive - but acceptable for most workloads. Messages sent this way will not be - truncated but may be dropped, in which case the DroppedLogs counter - will be incremented. The writev() call is atomic even on pipes for - messages up to PIPE_BUF size, which POSIX recommends to be at least - 512 and which is 4096 bytes on most modern operating systems. Any - larger message may be interleaved with messages from other processes. - Exceptionally for debugging purposes the file descriptor may also be - directed to a file, but doing so will significantly slow HAProxy down - as non-blocking calls will be ignored. Also there will be no way to - purge nor rotate this file without restarting the process. Note that - the configured syslog format is preserved, so the output is suitable - for use with a TCP syslog server. See also the "short" and "raw" - format below. - - - "stdout" / "stderr", which are respectively aliases for "fd@1" and - "fd@2", see above. - - - A ring buffer in the form "ring@", which will correspond to an - in-memory ring buffer accessible over the CLI using the "show events" - command, which will also list existing rings and their sizes. Such - buffers are lost on reload or restart but when used as a complement - this can help troubleshooting by having the logs instantly available. - - You may want to reference some environment variables in the address - parameter, see section 2.3 about environment variables. - - is an optional maximum line length. Log lines larger than this value - will be truncated before being sent. The reason is that syslog - servers act differently on log line length. All servers support the - default value of 1024, but some servers simply drop larger lines - while others do log them. If a server supports long lines, it may - make sense to set this value here in order to avoid truncating long - lines. Similarly, if a server drops long lines, it is preferable to - truncate them before sending them. Accepted values are 80 to 65535 - inclusive. The default value of 1024 is generally fine for all - standard usages. Some specific cases of long captures or - JSON-formatted logs may require larger values. You may also need to - increase "tune.http.logurilen" if your request URIs are truncated. - - is the log format used when generating syslog messages. It may be - one of the following : - - local Analog to rfc3164 syslog message format except that hostname - field is stripped. This is the default. - Note: option "log-send-hostname" switches the default to - rfc3164. - - rfc3164 The RFC3164 syslog message format. - (https://tools.ietf.org/html/rfc3164) - - rfc5424 The RFC5424 syslog message format. - (https://tools.ietf.org/html/rfc5424) - - priority A message containing only a level plus syslog facility between - angle brackets such as '<63>', followed by the text. The PID, - date, time, process name and system name are omitted. This is - designed to be used with a local log server. - - short A message containing only a level between angle brackets such as - '<3>', followed by the text. The PID, date, time, process name - and system name are omitted. This is designed to be used with a - local log server. This format is compatible with what the systemd - logger consumes. - - timed A message containing only a level between angle brackets such as - '<3>', followed by ISO date and by the text. The PID, process - name and system name are omitted. This is designed to be - used with a local log server. - - iso A message containing only the ISO date, followed by the text. - The PID, process name and system name are omitted. This is - designed to be used with a local log server. - - raw A message containing only the text. The level, PID, date, time, - process name and system name are omitted. This is designed to be - used in containers or during development, where the severity only - depends on the file descriptor used (stdout/stderr). - - A list of comma-separated ranges to identify the logs to sample. - This is used to balance the load of the logs to send to the log - server. The limits of the ranges cannot be null. They are numbered - from 1. The size or period (in number of logs) of the sample must be - set with parameter. - - - The size of the sample in number of logs to consider when balancing - their logging loads. It is used to balance the load of the logs to - send to the syslog server. This size must be greater or equal to the - maximum of the high limits of the ranges. - (see also parameter). - - must be one of the 24 standard syslog facilities : - - kern user mail daemon auth syslog lpr news - uucp cron auth2 ftp ntp audit alert cron2 - local0 local1 local2 local3 local4 local5 local6 local7 - - Note that the facility is ignored for the "short" and "raw" - formats, but still required as a positional field. It is - recommended to use "daemon" in this case to make it clear that - it's only supposed to be used locally. - - An optional level can be specified to filter outgoing messages. By default, - all messages are sent. If a maximum level is specified, only messages with a - severity at least as important as this level will be sent. An optional minimum - level can be specified. If it is set, logs emitted with a more severe level - than this one will be capped to this level. This is used to avoid sending - "emerg" messages on all terminals on some default syslog configurations. - Eight levels are known : - - emerg alert crit err warning notice info debug + configured with "log global". See "log" option for proxies for more details. log-send-hostname [] Sets the hostname field in the syslog header. If optional "string" parameter @@ -8840,6 +8710,8 @@ no log values are 80 to 65535 inclusive. The default value of 1024 is generally fine for all standard usages. Some specific cases of long captures or JSON-formatted logs may require larger values. + You may also need to increase "tune.http.logurilen" if your + request URIs are truncated. A list of comma-separated ranges to identify the logs to sample. This is used to balance the load of the logs to send to the log