From: Hyeonggeun Oh <[email protected]>
Add documentation for the dump_all_vars() sample fetch function in the
configuration manual. This function was introduced in the previous commit
to dump all variables in a given scope with optional prefix filtering.
The documentation includes:
- Function signature and return type
- Description of output format
- Explanation of scope and prefix arguments
- Usage examples for common scenarios
Changes based on feedback:
- Document the delimiter argument (third parameter)
- Explain binary hex encoding format (x...)
- Document address type support
- Document HTTP method type support
- Add performance warning about prefix filtering
- Clarify that function fails on buffer overflow rather than truncating
- Provide examples with custom delimiters
This completes the implementation of GitHub issue #1623.
---
doc/configuration.txt | 60 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 43f25a8c7..7a6fb9757 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -22928,6 +22928,66 @@ var(<var-name>[,<default>]) : undefined
return it as a string. Empty strings are permitted. See section 2.8 about
variables for details.
+dump_all_vars([<scope>][,<prefix>][,<delimiter>]) : string
+ Returns a list of all variables in the specified scope, optionally filtered
+ by name prefix and with a customizable delimiter.
+
+ Output format: var1=value1<delim>var2=value2<delim>...
+
+ Value encoding by type:
+ - Strings: quoted and escaped (", \, \r, \n, \b, \0)
+ Example: txn.name="John \"Doe\""
+ - Binary: hex-encoded with 'x' prefix, unquoted
+ Example: txn.data=x48656c6c6f
+ - Integers: unquoted decimal
+ Example: txn.count=42
+ - Booleans: unquoted "true" or "false"
+ Example: txn.active=true
+ - Addresses: unquoted IP address string
+ Example: txn.client=192.168.1.1
+ - HTTP Methods: quoted string
+ Example: req.method="GET"
+
+ Arguments:
+ - <scope> (optional): sess, txn, req, res, or proc. If omitted, the scope
+ is determined by context (txn for streams, sess for sessions, proc
+ otherwise).
+
+ - <prefix> (optional): filters variables whose names start with the
+ specified prefix (after removing the scope prefix).
+ Performance note: When using prefix filtering, all variables in the scope
+ are still visited. This should not be used with configurations involving
+ thousands of variables.
+
+ - <delimiter> (optional): string to separate variables. Defaults to ", "
+ (comma-space). Can be customized to any string.
+
+ Return value:
+ - On success: string containing all matching variables
+ - On failure: empty (sample fetch fails) if output buffer is too small.
+ The function will not truncate output; it fails completely to avoid
+ partial data.
+
+ This is particularly useful for debugging, logging, or exporting variable
+ states.
+
+ Examples:
+ # Dump all transaction variables
+ http-request return string %[dump_all_vars(txn)]
+
+ # Dump only variables starting with "user"
+ http-request set-header X-User-Vars "%[dump_all_vars(txn,user)]"
+
+ # Dump all process variables
+ http-request return string %[dump_all_vars(proc)]
+
+ # Custom delimiter (semicolon)
+ http-request set-header X-Vars "%[dump_all_vars(txn,,; )]"
+
+ # Prefix filter with custom delimiter
+ http-request set-header X-Session "%[dump_all_vars(sess,user,|)]"
+
+
wait_end : boolean
This fetch either returns true when the inspection period is over, or does
not fetch. It is only used in ACLs, in conjunction with content analysis to
--
2.48.1
