From c02cefce235c17b7809832735d315db675ee69ba Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Fri, 24 May 2024 16:18:20 +0200 Subject: [PATCH] DOC: config: uniformize the naming and description of custom log format args A significant number of actions now take arguments that are evaluated as log-format expressions. Some of them are called "fmt", others "string". The description of the argument sometimes just says "the log-format string" or "log format" or "custom log format" etc. Most of them do not mention the section to visit, and section 8.2 speaking about log-format is very centric on logs usage (the primary use case), making all of this very confusing for newcomers. Since section 8.2.6 is titled "Custom log format" and describes the syntax to be used with the "log-format" (and other) directives, let's call this "Custom log format" everywhere and mention section 8.2.6. When the field was called "string", it was also renamed to "fmt". It doesn't seem worth backporting this, unless it applies fine. --- doc/configuration.txt | 233 ++++++++++++++++++++++-------------------- 1 file changed, 122 insertions(+), 111 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index f97069ed5..ed4103677 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -2326,7 +2326,7 @@ set-var-fmt are only those using internal data, typically 'int(value)' or 'str(value)'. It is possible to reference previously allocated variables as well. These variables will then be readable (and modifiable) from the regular rule sets. - Please see section 8.2.6 for details on the custom log-format syntax. + Please see section 8.2.6 for details on the Custom log format syntax. Example: global @@ -6823,7 +6823,7 @@ email-alert to "email-alert myhostname", section 3.6 about mailers. -error-log-format +error-log-format Specifies the log format string to use in case of connection error on the frontend side. May be used in the following contexts: tcp, http @@ -7347,12 +7347,13 @@ http-check expect [min-recv ] [comment ] on-success is optional and can be used to customize the informational message reported in logs if the expect rule is successfully evaluated and if it is the last rule - in the tcp-check ruleset. is a log-format string. + in the tcp-check ruleset. is a Custom log format + string (see section 8.2.6). on-error is optional and can be used to customize the informational message reported in logs if an error occurred during the expect rule evaluation. is a - log-format string. + Custom log format string (see section 8.2.6). is a keyword indicating how to look for a specific pattern in the response. The keyword may be one of "status", "rstatus", "hdr", @@ -7398,17 +7399,18 @@ http-check expect [min-recv ] [comment ] match), "end" (suffix match), "sub" (substring match) or "reg" (regex match). If not specified, exact matching method is used. If the "name-lf" parameter is used, - is evaluated as a log-format string. If "value-lf" - parameter is used, is evaluated as a log-format - string. These parameters cannot be used with the regex - matching method. Finally, the header value is considered - as comma-separated list. Note that matchings are case - insensitive on the header names. + is evaluated as a Custom log format string (see + section 8.2.6). If "value-lf" parameter is used, + is evaluated as a log-format string. These parameters + cannot be used with the regex matching method. Finally, + the header value is considered as comma-separated + list. Note that matchings are case insensitive on the + header names. fhdr { name | name-lf } [ -m ] [ { value | value-lf } [ -m ] : test the specified full header pattern on the HTTP - response headers. It does exactly the same than "hdr" + response headers. It does exactly the same as the "hdr" keyword, except the full header value is tested, commas are not considered as delimiters. @@ -7431,12 +7433,13 @@ http-check expect [min-recv ] [comment ] of a dynamic page, or to detect a failure when a specific error appears on the check page (e.g. a stack trace). - string-lf : test a log-format string match in the HTTP response body. - A health check response will be considered valid if the - response's body contains the string resulting of the - evaluation of , which follows the log-format rules. - If prefixed with "!", then the response will be - considered invalid if the body contains the string. + string-lf : test a Custom log format string (see section 8.2.6) match + in the HTTP response body. A health check response will + be considered valid if the response's body contains the + string resulting of the evaluation of , which + follows the log-format rules. If prefixed with "!", then + the response will be considered invalid if the body + contains the string. It is important to note that the responses will be limited to a certain size defined by the global "tune.bufsize" option, which defaults to 16384 bytes. @@ -7502,9 +7505,10 @@ http-check send [meth ] [{ uri | uri-lf }>] [ver ] other URI. Query strings are permitted. uri-lf is optional and set the URI referenced in the HTTP requests - using the log-format string . It defaults to "/" which - is accessible by default on almost any server, but may be - changed to any other URI. Query strings are permitted. + using the Custom log format (see section 8.2.6). It + defaults to "/" which is accessible by default on almost any + server, but may be changed to any other URI. Query strings + are permitted. ver is the optional HTTP version string. It defaults to "HTTP/1.0" but some servers might behave incorrectly in HTTP @@ -7514,16 +7518,16 @@ http-check send [meth ] [{ uri | uri-lf }>] [ver ] hdr adds the HTTP header field whose name is specified in and whose value is defined by , which follows - to the log-format rules. + the Custom log format rules described in section 8.2.6. body add the body defined by to the request sent during HTTP health checks. If defined, the "Content-Length" header is thus automatically added to the request. - body-lf add the body defined by the log-format string to the - request sent during HTTP health checks. If defined, the - "Content-Length" header is thus automatically added to the - request. + body-lf add the body defined by the Custom log format (see + section 8.2.6) to the request sent during HTTP health + checks. If defined, the "Content-Length" header is thus + automatically added to the request. In addition to the request line defined by the "option httpchk" directive, this one is the valid way to add some headers and optionally a body to the @@ -7632,7 +7636,7 @@ http-check set-var-fmt([,...]) Is a sample-fetch expression potentially followed by converters. - This is the value expressed using log-format rules (see Custom + This is the value expressed using Custom log format (see Custom Log Format in section 8.2.6). Examples : @@ -7715,7 +7719,7 @@ http-error status [content-type ] file is not empty, its content-type must be set as argument to "content-type", otherwise, any "content-type" argument is ignored. is - evaluated as a log-format string. + evaluated as a Custom log format (see section 8.2.6). lf-string specifies the log-format string to use as response payload. The content-type must always be set as @@ -7723,8 +7727,9 @@ http-error status [content-type ] hdr adds to the response the HTTP header field whose name is specified in and whose value is defined by - , which follows to the log-format rules. - This parameter is ignored if an errorfile is used. + , which follows the Custom log format rules (see + section 8.2.6). This parameter is ignored if an + errorfile is used. This directive may be used instead of "errorfile", to define a custom error message. As "errorfile" directive, it is used for errors detected and @@ -8339,8 +8344,8 @@ no log # level and send in tcp log "${LOCAL_SYSLOG}:514" local0 notice # send to local server -log-format - Specifies the log format string to use for traffic logs +log-format + Specifies the custom log format string to use for traffic logs May be used in the following contexts: tcp, http @@ -8359,8 +8364,8 @@ log-format "log-format" directive overrides previous "option tcplog", "log-format", "option httplog" and "option httpslog" directives. -log-format-sd - Specifies the RFC5424 structured-data log format string +log-format-sd + Specifies the Custom log format string used to produce RFC5424 structured-data May be used in the following contexts: tcp, http @@ -10924,8 +10929,8 @@ redirect scheme [code ]