DOC-776 | AQL query recording

site/content/3.12/develop/http-api/monitoring/logs.md

@@ -864,7 +864,9 @@ paths:
           description: |
             The name of a database. Which database you use doesn't matter as long
             as the user account you authenticate with has at least read access
-            to this database.
+            to this database and administrate access to the `_system` database.
+            If `--log.recording-api-enabled` is set to `jwt`, you need to use
+            a superuser token to access the endpoint.
           schema:
             type: string
       responses:
@@ -1002,3 +1004,173 @@ Content-Length: 257
 }
 ```
 {{< /expand >}}
+
+## Get recent AQL queries
+
+```openapi
+paths:
+  /_db/{database-name}/_admin/server/aql-queries:
+    get:
+      operationId: getRecentAqlQueries
+      description: |
+        Get a list of the most recent AQL queries with a timestamp and
+        information about the submitted query.
+        This feature is for debugging purposes.
+
+        You can control how much memory is used to record AQL queries with the
+        `--server.aql-recording-memory-limit` startup option.
+
+        You can disable AQL query and API call recording via the
+        `--log.recording-api-enabled` startup option.
+        The endpoint returns an empty list of queries in this case.
+      parameters:
+        - name: database-name
+          in: path
+          required: true
+          example: _system
+          description: |
+            The name of a database. Which database you use doesn't matter as long
+            as the user account you authenticate with has at least read access
+            to this database and administrate access to the `_system` database.
+            If `--log.recording-api-enabled` is set to `jwt`, you need to use
+            a superuser token to access the endpoint.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: |
+            The 
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - error
+                  - code
+                  - result
+                properties:
+                  error:
+                    description: |
+                      A flag indicating that no error occurred.
+                    type: boolean
+                    example: false
+                  code:
+                    description: |
+                      The HTTP response status code.
+                    type: integer
+                    example: 200
+                  result:
+                    description: |
+                      The request result.
+                    type: object
+                    required:
+                      - queries
+                    properties:
+                      queries:
+                        description: |
+                          A list of the recent AQL queries.
+                          Empty if AQL query and API call recording is disabled.
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            timeStamp:
+                              description: |
+                                The date and time of the request in ISO 8601 format.
+                              type: string
+                              format: date-time
+                            queryString:
+                              description: |
+                                The AQL query.
+                              type: string
+                            bindParameters:
+                              description: |
+                                Key/value pairs representing the bind variables.
+                              type: object
+                            database:
+                              description: |
+                                The database name.
+                              type: string
+        '401':
+          description: |
+            The user account has insufficient permissions for the selected database.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - error
+                  - code
+                  - errorNum
+                  - errorMessage
+                properties:
+                  error:
+                    description: |
+                      A flag indicating that an error occurred.
+                    type: boolean
+                    example: true
+                  code:
+                    description: |
+                      The HTTP response status code.
+                    type: integer
+                    example: 401
+                  errorNum:
+                    description: |
+                      ArangoDB error number for the error that occurred.
+                    type: integer
+                  errorMessage:
+                    description: |
+                      A descriptive error message.
+                    type: string
+      tags:
+        - Monitoring
+```
+
+{{< comment >}}
+Example not generated because it changes on every run and there can be many internal queries.
+{{< /comment >}}
+
+```bash
+curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/server/aql-queries
+```
+
+{{< expand title="Show output" >}}
+```bash
+HTTP/1.1 200 OK
+X-Arango-Queue-Time-Seconds: 0.000000
+Strict-Transport-Security: max-age=31536000 ; includeSubDomains
+Expires: 0
+Pragma: no-cache
+Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
+Content-Security-Policy: frame-ancestors 'self'; form-action 'self';
+X-Content-Type-Options: nosniff
+Server: ArangoDB
+Connection: Keep-Alive
+Content-Type: application/json; charset=utf-8
+Content-Length: 377
+
+{
+  "error": false,
+  "code": 200,
+  "result": {
+    "queries": [
+      {
+        "timeStamp": "2025-07-02T16:33:32Z",
+        "queryString": "FOR s in @@collection FILTER s.time < @start RETURN s._key",
+        "database": "_system",
+        "bindParameters": {
+          "@collection": "_statistics",
+          "start": 1751470412.3836362
+        }
+      },
+      {
+        "timeStamp": "2025-07-02T16:26:01Z",
+        "queryString": "FOR doc IN coll RETURN doc",
+        "database": "_system",
+        "bindParameters": {}
+      }
+    ]
+  }
+}
+```
+{{< /expand >}}

site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md

@@ -309,6 +309,17 @@ is for debugging purposes.
 See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
 for details.
 
+#### AQL query recording
+
+<small>Introduced in: v3.12.6</small>
+
+A new `/_admin/server/aql-queries` endpoint has been added to let you retrieve a
+list of the most recent AQL queries with a timestamp and information about the
+submitted queries. This feature is for debugging purposes.
+
+See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-aql-queries)
+for details.
+
 ### Endpoints augmented
 
 #### View API

site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -2174,8 +2174,7 @@ You can configure the memory limit for this feature with the following startup o
 - `--server.memory-per-api-call-list`: 
   The amount of memory used for a single API call record list (default: `100000` bytes)
 
-This means that approximately 25 MB of memory are reserved by default.
-
+This means that approximately 25 MB of memory is reserved by default.
 
 API call recording is enabled by default but you can disable it via the new
 `--server.api-call-recording` startup option.
@@ -2189,6 +2188,35 @@ impact of this feature:
 
 See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
 for details.
+### AQL query recording
+
+<small>Introduced in: v3.12.6</small>
+
+A new `/_admin/server/aql-queries` endpoint has been added to let you retrieve a
+list of the most recent AQL queries with a timestamp and information about the
+submitted query. This feature is for debugging purposes.
+
+You can configure the memory limit for this feature with the following startup option:
+
+- `--server.aql-recording-memory-limit`: 
+  The amount of memory used for recording AQL queries (default: `25600000` bytes)
+
+This means that approximately 25 MB of memory is reserved by default.
+
+API call recording is enabled by default but you can disable it via the new
+`--log.recording-api-enabled` startup option, which also affects the
+API call recording. You can set it to `jwt` to require a superuser token instead
+of write access to the `_system` database for accessing the endpoint.
+
+A metric has been added for the time spent on AQL query recording to track the
+impact of this feature:
+
+| Label | Description |
+|:------|:------------|
+| `arangodb_aql_recording_call_time` | Execution time histogram for AQL recording calls in nanoseconds. |
+
+See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-aql-queries)
+for details.
 
 ## Client tools