Skip to content

DOC-776 | AQL query recording #735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 243 additions & 3 deletions site/content/3.12/develop/http-api/monitoring/logs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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 >}}
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
39 changes: 37 additions & 2 deletions site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
Loading