DOC-776 | AQL query recording

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

@@ -560,7 +560,7 @@ paths:
                     Logs various information related to ArangoDB's use of the
                     RocksDB storage engine, like the initialization and
                     file operations.
-                    
+
                     RocksDB's internal log messages are passed through using the
                     `rocksdb` log topic.
                   type: string
@@ -848,12 +848,14 @@ paths:
       operationId: getRecentApiCalls
       description: |
         Get a list of the most recent requests with a timestamp and the endpoint.
+        In cluster deployments, the list contains only those requests that were
+        submitted to the Coordinator you call this endpoint on.
         This feature is for debugging purposes.
 
         You can control how much memory is used to record API calls with the
         `--server.api-recording-memory-limit` startup option.
 
-        You can disable this endpoint
+        You can disable this and the `/_admin/server/aql-queries` endpoint
         with the `--log.recording-api-enabled` startup option.
 
         Whether API calls are recorded is independently controlled by the
@@ -867,7 +869,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:
@@ -1067,3 +1071,239 @@ 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. In cluster deployments, the list
+        contains only those queries that were submitted to the Coordinator you
+        call this endpoint on. 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 this and the `/_admin/server/api-calls` endpoint
+        with the `--log.recording-api-enabled` startup option.
+
+        Whether AQL queries are recorded is independently controlled by the
+        `--server.aql-query-recording` startup option.
+        The endpoint returns an empty list of queries if turned off.
+      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: |
+            Returns the recorded AQL queries.
+          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 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
+                            query:
+                              description: |
+                                The AQL query.
+                              type: string
+                            bindVars:
+                              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
+        '403':
+          description: |
+            The recording API has been disabled.
+          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: 403
+                  errorNum:
+                    description: |
+                      ArangoDB error number for the error that occurred.
+                    type: integer
+                  errorMessage:
+                    description: |
+                      A descriptive error message.
+                    type: string
+        '501':
+          description: |
+            The method has not been called on a Coordinator or single server.
+          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: 501
+                  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: 353
+
+{
+  "error": false,
+  "code": 200,
+  "result": {
+    "queries": [
+      {
+        "timeStamp": "2025-07-02T16:33:32Z",
+        "query": "FOR s in @@collection FILTER s.time < @start RETURN s._key",
+        "database": "_system",
+        "bindVars": {
+          "@collection": "_statistics",
+          "start": 1751470412.3836362
+        }
+      },
+      {
+        "timeStamp": "2025-07-02T16:26:01Z",
+        "query": "FOR doc IN coll RETURN doc",
+        "database": "_system",
+        "bindVars": {}
+      }
+    ]
+  }
+}
+```
+{{< /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

@@ -2170,9 +2170,9 @@ is for debugging purposes.
 You can configure the memory limit for this feature with the following startup option:
 
 - `--server.api-recording-memory-limit`:
-  Size limit for the list of API call records (default: `25600000`).
+  Size limit for the list of API call records (default: `26214400`).
 
-This means that 25 MB of memory is reserved by default.
+This means that 25 MiB 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.
@@ -2191,6 +2191,41 @@ 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`:
+  Size limit for the list of AQL query records (default: `26214400` bytes)
+
+This means that 25 MiB of memory is reserved by default.
+
+AQL query recording is enabled by default but you can disable it via the new
+`--server.aql-query-recording` startup option.
+
+This and the `/_admin/server/api-calls` endpoint are referred to as the
+recording API, which exposes the recorded API calls and AQL queries. It is
+enabled by default. Users with administrative access to the `_system` database
+can call the endpoints. You can further restrict the access to only the
+superuser by setting `--log.recording-api-enabled` to `jwt`, or disable the
+endpoints altogether by setting the option to `false`.
+
+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
 
 ### Protocol aliases for endpoints