From 3c5e2dd9845185612b10ffe96eab5f0edc01d296 Mon Sep 17 00:00:00 2001 From: HAProxy Community Date: Wed, 23 Oct 2024 00:50:20 +0000 Subject: [PATCH] Update docs for dev --- docs/dev/configuration.html | 76 ++++++++++++++++++++++++++++++++++--- docs/dev/intro.html | 8 ++-- docs/dev/management.html | 8 ++-- 3 files changed, 78 insertions(+), 14 deletions(-) diff --git a/docs/dev/configuration.html b/docs/dev/configuration.html index 3025f52..f2182b7 100644 --- a/docs/dev/configuration.html +++ b/docs/dev/configuration.html @@ -2,7 +2,7 @@ - HAProxy version 3.1-dev10-40 - Configuration Manual + HAProxy version 3.1-dev10-50 - Configuration Manual @@ -4356,6 +4356,8 @@ weight + when + word ws @@ -4400,7 +4402,7 @@ You can use left and right arrow keys to navigate between chapters.

- Converted with haproxy-dconv v0.4.2-15 on 2024/10/17 + Converted with haproxy-dconv v0.4.2-15 on 2024/10/22

@@ -4411,7 +4413,7 @@

Configuration Manual

-

version 3.1-dev10-40

+

version 3.1-dev10-50

2024/10/16
@@ -23575,9 +23577,10 @@

us_ltime(format[,offset])integerstring us_utime(format[,offset])integerstring utime(format[,offset])integerstring +when(condition)anysame word(index,delimiters[,count])stringstring -wt6([avalanche])binaryinteger keywordinput typeoutput type +wt6([avalanche])binaryinteger x509_v_err_strintegerstring xor(value)integerinteger xxh3([seed])binaryinteger @@ -24963,7 +24966,68 @@

# e.g. 20140710162350 127.0.0.1:57325 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp -

word(<index>,<delimiters>[,<count>])
Extracts the nth word counting from the beginning (positive index) or from
+
when(<condition>)
Evaluates the condition and when true, passes the input sample as-is to the
+output, otherwise return nothing. This is designed specifically to produce
+some rarely needed data that should only be emitted under certain conditions,
+such as debugging information when an error is met.
+
+The condition is made of a keyword among the list below, optionally preceeded
+by an exclamation mark ('!') to negate it:
+
+  - "error" returns true when an error was encountered during the processing
+    of the request or stream. It uses the same rules as "dontlog-normal"
+    (e.g. a successful redispatch counts as an error).
+
+  - "forwarded" returns true when the request was forwarded to a backend
+    server
+
+  - "normal" returns true when no error happened (this is equivalent to
+    "!error").
+
+  - "processed" returns true when the request was either forwarded to a
+    backend server, or processed by an applet.
+
+  - "stopping" returns true if the process is currently stopping when the
+    rule is evaluated
+
+  - "toapplet" returns true when the request was processed by an applet.
+
+Note that the content is evaluated in any case, so doing this does not avoid
+the generation of that information. It's only meant to avoid producing that
+information.
+
+An example would be to add backend stream debugging information in the logs
+only when an error was encountered during processing, or logging extra
+information when stopping, etc.
+

+Example:
+
+# log "dbg={-}" when fine, or "dbg={... debug info ...}" on error:
+log-format "$HAPROXY_HTTP_LOG_FMT dbg={%[bs.debug_str,when(!normal)]}"
+
+Here, the "dbg" field in the log will only contain an dash ('-') to
+indicate a missing content when the rule is not validated, and will emit a
+whole debugging block when it is.
+

+
Example
+  # only emit the backend src/port when a real connection was issued:
+  log-format "$HAPROXY_HTTP_LOG_FMT \
+             src=[%[bc_src,when(forwarded)]:%[bc_src_port,when(forwarded)]]"
+
+Since it kills the evaluation of the expression when it is not true, it is
+also possible to use it to stop a subsequent converter from being called.
+This may for example be used to call the debug() converter only upon error,
+to log an element only when absolutely necessary.
+

+Example:
+
+# emit the whole response headers list to stderr only on error and only
+# when the output is a connection. We abuse a dummy variable here.
+http-after-response set-var(res.test) \
+              res.hdrs,when(error),when(forwarded),debug(hdrs,stderr)
+

+
See also: debug converter

+
word(<index>,<delimiters>[,<count>])
Extracts the nth word counting from the beginning (positive index) or from
 the end (negative index) considering given delimiters from an input string.
 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
 Empty words are skipped. This means that delimiters at the start or end of
@@ -31205,7 +31269,7 @@ 
11
 						

 						

 						

-							HAProxy 3.1-dev10-40 – Configuration Manual

+							HAProxy 3.1-dev10-50 – Configuration Manual

 							, 2024/10/16
 						

 					
diff --git a/docs/dev/intro.html b/docs/dev/intro.html
index 4b87f6e..7010096 100644
--- a/docs/dev/intro.html
+++ b/docs/dev/intro.html
@@ -2,7 +2,7 @@
 
 	
 		
-		HAProxy version 3.1-dev10-40 - Starter Guide
+		HAProxy version 3.1-dev10-50 - Starter Guide
 		
 		
 		
@@ -484,7 +484,7 @@
 					You can use left and right arrow keys to navigate between chapters.

 				

 				

-					Converted with haproxy-dconv v0.4.2-15 on 2024/10/17
+					Converted with haproxy-dconv v0.4.2-15 on 2024/10/22
 				

 			
 			
@@ -495,7 +495,7 @@
 						

                             

 							
Starter Guide

-							
version 3.1-dev10-40

+							
version 3.1-dev10-50

 							

 								

 								
@@ -2515,7 +2515,7 @@ 
4.4.<
 						

 						

 						

-							HAProxy 3.1-dev10-40 – Starter Guide

+							HAProxy 3.1-dev10-50 – Starter Guide

 							, 
 						

 					

diff --git a/docs/dev/management.html b/docs/dev/management.html
index 4ab43a1..18387aa 100644
--- a/docs/dev/management.html
+++ b/docs/dev/management.html
@@ -2,7 +2,7 @@
 
 	
 		
-		HAProxy version 3.1-dev10-40 - Management Guide
+		HAProxy version 3.1-dev10-50 - Management Guide
 		
 		
 		
@@ -646,7 +646,7 @@
 					You can use left and right arrow keys to navigate between chapters.

 				

 				

-					Converted with haproxy-dconv v0.4.2-15 on 2024/10/17
+					Converted with haproxy-dconv v0.4.2-15 on 2024/10/22
 				

 			
 			
@@ -657,7 +657,7 @@
 						

                             

 							
Management Guide

-							
version 3.1-dev10-40

+							
version 3.1-dev10-50

 							

 								

 								
@@ -5339,7 +5339,7 @@ 
13
 						

 						

 						

-							HAProxy 3.1-dev10-40 – Management Guide

+							HAProxy 3.1-dev10-50 – Management Guide

 							,