mirrors/haproxy
1
0
Fork 0
mirror of https://git.haproxy.org/git/haproxy.git/ synced 2025-09-21 13:51:26 +02:00
Code Issues Projects Releases Wiki Activity

DOC: config: unify "log" directive doc

Browse Source 
"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.
This commit is contained in:
Aurelien DARRAGON 2023-09-25 16:10:02 +02:00 committed by Christopher Faulet
parent 19a1210dcd
commit e5d23d8676
1 changed files with 3 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
doc/configuration.txt
View File

@ -1840,137 +1840,7 @@ log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>]
<facility> [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".
<address> 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@<number>", 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@<name>", 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.
<length> 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.
<format> 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).
<ranges> 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 <sample_size> parameter.
<sample_size>
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 <ranges> parameter).
<facility> 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 [<string>]
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.
<ranges> 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