Added startup option --query.log-failed-queries to optionally log all… (#1140)

jsteemann · Simran-B · nerpaula · web-flow · commit cea2bc1d6f84 · 2022-11-07T15:29:51.000+08:00
* Added startup option --query.log-failed-queries to optionally log all failed AQL queries to the server log. The option is turned off by default.

* Update programs-arangod-query.md

* updated after functionality change

* Formatting

* add new option

* fixed

* adjusted for all relevant versions

* AE

* Review

* Release notes

Co-authored-by: Simran &lt;Simran-B@users.noreply.github.com&gt;
Co-authored-by: Simran Spiller &lt;simran@arangodb.com&gt;
Co-authored-by: Paula Mihu &lt;97217318+nerpaula@users.noreply.github.com&gt;
diff --git a/3.10/programs-arangod-query.md b/3.10/programs-arangod-query.md
@@ -130,6 +130,42 @@ queries early. When set to *false*, AQL queries that produce warnings will not
 abort and return the warnings along with the query results.
 The option can also be overridden for each individual AQL query.
 
+## Logging failed AQL queries
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+`--query.log-failed value`
+
+If set to `true`, all failed AQL queries are logged to the server log. This
+option can be used during development, or to catch unexpected failed queries
+in production.
+
+The option is turned off by default.
+
+## Logging AQL queries with high memory usage
+
+`--query.log-memory-usage-threshold value`
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+This option determines the peak memory usage threshold for AQL queries from
+which on a warning is logged if queries exceed it. This is useful for
+finding queries that use a large amount of memory.
+
+The default value is `4294967296` (4 GB).
+
+## Controlling length of logged query strings and bind parameter values
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+`--query.max-artifact-log-length value`
+
+This option determines the maximum length of logged query strings and bind parameter 
+values. This allows truncating overly long query strings and bind parameter values
+to a reasonable length in log files.
+
+The default value is `4096` bytes.
+
 ## Requiring `WITH` statements
 
 <small>Introduced in: v3.7.12</small>
diff --git a/3.10/release-notes-new-features310.md b/3.10/release-notes-new-features310.md
@@ -868,6 +868,19 @@ temporary data:
 
 For more information on the new options, please refer to [ArangoDB Server Pregel Options](programs-arangod-pregel.html).
 
+### AQL query logging
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+There are three new startup options to configure how AQL queries are logged:
+
+- `--query.log-failed` for logging all failed AQL queries, to be used during
+  development or to catch unexpected failed queries in production (off by default)
+- `--query.log-memory-usage-threshold` to define a peak memory threshold from
+  which on a warning is logged for AQL queries that exceed it (default: 4 GB)
+- `--query.max-artifact-log-length` for controlling the length of logged query
+  strings and bind parameter values. Both are truncated to 4096 bytes by default.
+
 Read from Followers in Clusters (Enterprise Edition)
 ----------------------------------------------------
 
diff --git a/3.11/programs-arangod-query.md b/3.11/programs-arangod-query.md
@@ -130,6 +130,42 @@ queries early. When set to *false*, AQL queries that produce warnings will not
 abort and return the warnings along with the query results.
 The option can also be overridden for each individual AQL query.
 
+## Logging failed AQL queries
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+`--query.log-failed value`
+
+If set to `true`, all failed AQL queries are logged to the server log. This
+option can be used during development, or to catch unexpected failed queries
+in production.
+
+The option is turned off by default.
+
+## Logging AQL queries with high memory usage
+
+`--query.log-memory-usage-threshold value`
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+This option determines the peak memory usage threshold for AQL queries from
+which on a warning is logged if queries exceed it. This is useful for
+finding queries that use a large amount of memory.
+
+The default value is `4294967296` (4 GB).
+
+## Controlling length of logged query strings and bind parameter values
+
+<small>Introduced in: v3.9.5, v3.10.2</small>
+
+`--query.max-artifact-log-length value`
+
+This option determines the maximum length of logged query strings and bind parameter 
+values. This allows truncating overly long query strings and bind parameter values
+to a reasonable length in log files.
+
+The default value is `4096` bytes.
+
 ## Requiring `WITH` statements
 
 <small>Introduced in: v3.7.12</small>
diff --git a/3.9/programs-arangod-query.md b/3.9/programs-arangod-query.md
@@ -130,6 +130,42 @@ queries early. When set to *false*, AQL queries that produce warnings will not
 abort and return the warnings along with the query results.
 The option can also be overridden for each individual AQL query.
 
+## Logging failed AQL queries
+
+<small>Introduced in: v3.9.5</small>
+
+`--query.log-failed value`
+
+If set to `true`, all failed AQL queries are logged to the server log. This
+option can be used during development, or to catch unexpected failed queries
+in production.
+
+The option is turned off by default.
+
+## Logging AQL queries with high memory usage
+
+`--query.log-memory-usage-threshold value`
+
+<small>Introduced in: v3.9.5</small>
+
+This option determines the peak memory usage threshold for AQL queries from
+which on a warning is logged if queries exceed it. This is useful for
+finding queries that use a large amount of memory.
+
+The default value is `4294967296` (4 GB).
+
+## Controlling length of logged query strings and bind parameter values
+
+<small>Introduced in: v3.9.5</small>
+
+`--query.max-artifact-log-length value`
+
+This option determines the maximum length of logged query strings and bind parameter 
+values. This allows truncating overly long query strings and bind parameter values
+to a reasonable length in log files.
+
+The default value is `4096` bytes.
+
 ## Requiring `WITH` statements
 
 <small>Introduced in: v3.7.12</small>
diff --git a/3.9/release-notes-new-features39.md b/3.9/release-notes-new-features39.md
@@ -569,6 +569,19 @@ A pseudo log topic `"all"` was added. Setting the log level for the "all" log
 topic will adjust the log level for **all existing log topics**. For example,
 `--log.level all=debug` will set all log topics to log level "debug".
 
+### AQL query logging
+
+<small>Introduced in: v3.9.5</small>
+
+There are three new startup options to configure how AQL queries are logged:
+
+- `--query.log-failed` for logging all failed AQL queries, to be used during
+  development or to catch unexpected failed queries in production (off by default)
+- `--query.log-memory-usage-threshold` to define a peak memory threshold from
+  which on a warning is logged for AQL queries that exceed it (default: 4 GB)
+- `--query.max-artifact-log-length` for controlling the length of logged query
+  strings and bind parameter values. Both are truncated to 4096 bytes by default.
+
 Overload control
 ----------------
 
