From: Aurelien DARRAGON Date: Thu, 30 May 2024 15:34:00 +0000 (+0200) Subject: DOC: config: add documentation for log profiles X-Git-Tag: v3.1-dev1~13 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8fa4036daee77a174dee31bc5a7cbf65d4f5943b;p=thirdparty%2Fhaproxy.git DOC: config: add documentation for log profiles Now that log-profile parsing logic has been implemented in "MINOR: log: add log-profile parsing logic" and is actually effective since "MEDIUM: log: handle log-profile in process_send_log()", let's document the feature and add some examples. Log-profile section is declared like this: log-profile myprof log-tag "custom-tag" on error format "%ci: error" on any format "(custom httplog) ${HAPROXY_HTTP_LOG_FMT}" sd "[exampleSDID@1234 step=\"accept\" id=\"%ID\"]" (check out the documentation for the full list of options, some options are only relevant under specific contexts) And used this way (from usual "log" directive lines): global log stdout format rfc5424 profile myprof local0 -------------- For now, the use of log-profiles is somewhat limited because we lack the ability to explicitly trigger the log building process at specific steps during the stream handling, but it should gain more traction over the time as the feature evolves and new mechanisms allowing the emission of logs at expected processing steps will be added. It should partially fix GH #401 --- diff --git a/doc/configuration.txt b/doc/configuration.txt index d85d403609..deaea4b420 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -114,6 +114,7 @@ Summary 8.3.2. Logging before waiting for the stream to terminate 8.3.3. Raising log level upon errors 8.3.4. Disabling logging of successful connections +8.3.5. Log profiles 8.4. Timing events 8.5. Stream state at disconnection 8.6. Non-printable characters @@ -2059,7 +2060,7 @@ localpeer See also "-L" in the management guide and "peers" section below. log [len ] [format ] [sample :] - [max level [min level]] + [profile ] [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". See "log" option for proxies for more details. @@ -8141,7 +8142,7 @@ load-server-state-from-file { global | local | none } log global log [len ] [format ] [sample :] - [ []] + [profile ] [ []] no log Enable per-instance logging of events and traffic. @@ -8158,10 +8159,9 @@ no log Arguments : global should be used when the instance's logging parameters are the same as the global ones. This is the most common usage. "global" - replaces , and with those of the log - entries found in the "global" section. Only one "log global" - statement may be used per instance, and this form takes no other - parameter. + replaces all log arguments with those of the log entries found + in the "global" section. Only one "log global" statement may be + used per instance, and this form takes no other parameter. indicates where to send the logs. It takes the same format as for the "global" section's logs, and can be one of : @@ -8287,6 +8287,10 @@ no log be used in containers or during development, where the severity only depends on the file descriptor used (stdout/stderr). + name of the optional "log-profile" section that will be + considered during the log building process to override some + log options. Check out "8.3.5. Log profiles" for more info. + must be one of the 24 standard syslog facilities : kern user mail daemon auth syslog lpr news @@ -26307,6 +26311,82 @@ useful information from the logs. Do this only if you have no other alternative. +8.3.5. Log profiles +------------------- + +While some directives such as "log-format", "log-format-sd", "error-log-format" +or "log-tag" make it possible to configure log formatting globally or at the +proxy level, it may be relevant to configure such settings as close as possible +to the log endpoints, that is, per "log" directive. + +This is where "log-profile" section comes into play: "log-profile" may be +defined anywhere in the configuration. This section accepts a set of different +keywords that are used to describe how the logs emitted for a given `log` +directive should be built. + +From a "log" directive, one can choose to use a specific log-profile by its +name. The same profile may be used from multiple "log" directives. + +log-profile + Creates a new log profile identified as + +log-tag + Override syslog log tag set globally or per-proxy using "log-tag" directive. + +on [format ] [sd ] + Override the log-format string normally used to build the log line at + logging step. is used to override "log-format" or + "error-log-format" strings (depending on the ) whereas is + used to override "log-format-sd" string. Possible values for are: + + - "accept" : override log-format if the log is generated right after + frontend conn was accepted + - "request" : override log-format if the log is generated after client + request was received + - "connect" : override log-format if the log is generated after backend + connection establishment + - "response" : override log-format if the log is generated during server + response handling + - "close" : override log-format if the log is generated at the final + transaction (txn) step + - "error" : override error-log-format for if the log is generated due + to a transaction error + - "any" : override both log-format and error-log-format for all logging + steps, unless a more precise step override is declared. + + This setting is only relevant for "log" directives used from contexts where + using "log-format" directive makes sense (e.g.: http and tcp proxies). + Else it will simply be ignored. + + Example : + + log-profile myprof + + log-tag "custom-tag" + + on error format "%ci: error" + on any sd "custom-sd" + + listen myproxy + mode http + option httplog + log-tag "normal" + + log stdout format rfc5424 local0 + # success: + # <134>1 2024-06-12T10:09:11.823400+02:00 - normal 224482 - - 127.0.0.1:53594 [12/Jun/2024:10:09:11.814] myproxy myproxy/ 0/-1/-1/-1/0 200 49 - - LR-- 1/1/0/0/0 0/0 "GET / HTTP/1.1" + # + # error: + # <134>1 2024-06-12T10:09:44.810929+02:00 - normal 224482 - - 127.0.0.1:59258 [12/Jun/2024:10:09:44.426] myproxy myproxy/ -1/-1/-1/-1/384 400 0 - - CR-- 1/1/0/0/0 0/0 "" + + log 127.0.0.1:514 format rfc5424 profile myprof local0 + # success: + # <134>1 2024-06-12T10:09:11.823428+02:00 - custom-tag 224482 - custom-sd 127.0.0.1:53594 [12/Jun/2024:10:09:11.814] myproxy myproxy/ 0/-1/-1/-1/0 200 49 - - LR-- 1/1/0/0/0 0/0 "GET / HTTP/1.1" + # + # error: + # <134>1 2024-06-12T10:09:51.566524+02:00 - custom-tag 224482 - - 127.0.0.1: error + + 8.4. Timing events ------------------