Skip to content

Commit 73428ea

Browse files
Simran-Bnerpaula
Simran-B
and
nerpaula
authored
DOC-776 | AQL query recording (#735)
* AQL query recording API * Fix text about startup option, add more status codes * Rework release notes, adjust attribute names * Fix copy-paste mistake * Per Coordinator recording in clusters * fix merge error --------- Co-authored-by: Paula Mihu <[email protected]> Co-authored-by: Paula <[email protected]>
1 parent 85de2a3 commit 73428ea

File tree

6 files changed

+584
-10
lines changed

6 files changed

+584
-10
lines changed

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

Lines changed: 243 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,7 @@ paths:
568568
Logs various information related to ArangoDB's use of the
569569
RocksDB storage engine, like the initialization and
570570
file operations.
571-
571+
572572
RocksDB's internal log messages are passed through using the
573573
`rocksdb` log topic.
574574
type: string
@@ -856,12 +856,14 @@ paths:
856856
operationId: getRecentApiCalls
857857
description: |
858858
Get a list of the most recent requests with a timestamp and the endpoint.
859+
In cluster deployments, the list contains only those requests that were
860+
submitted to the Coordinator you call this endpoint on.
859861
This feature is for debugging purposes.
860862
861863
You can control how much memory is used to record API calls with the
862864
`--server.api-recording-memory-limit` startup option.
863865
864-
You can disable this endpoint
866+
You can disable this and the `/_admin/server/aql-queries` endpoint
865867
with the `--log.recording-api-enabled` startup option.
866868
867869
Whether API calls are recorded is independently controlled by the
@@ -875,7 +877,9 @@ paths:
875877
description: |
876878
The name of a database. Which database you use doesn't matter as long
877879
as the user account you authenticate with has at least read access
878-
to this database.
880+
to this database and administrate access to the `_system` database.
881+
If `--log.recording-api-enabled` is set to `jwt`, you need to use
882+
a superuser token to access the endpoint.
879883
schema:
880884
type: string
881885
responses:
@@ -1075,3 +1079,239 @@ Content-Length: 257
10751079
}
10761080
```
10771081
{{< /details >}}
1082+
1083+
## Get recent AQL queries
1084+
1085+
```openapi
1086+
paths:
1087+
/_db/{database-name}/_admin/server/aql-queries:
1088+
get:
1089+
operationId: getRecentAqlQueries
1090+
description: |
1091+
Get a list of the most recent AQL queries with a timestamp and
1092+
information about the submitted query. In cluster deployments, the list
1093+
contains only those queries that were submitted to the Coordinator you
1094+
call this endpoint on. This feature is for debugging purposes.
1095+
1096+
You can control how much memory is used to record AQL queries with the
1097+
`--server.aql-recording-memory-limit` startup option.
1098+
1099+
You can disable this and the `/_admin/server/api-calls` endpoint
1100+
with the `--log.recording-api-enabled` startup option.
1101+
1102+
Whether AQL queries are recorded is independently controlled by the
1103+
`--server.aql-query-recording` startup option.
1104+
The endpoint returns an empty list of queries if turned off.
1105+
parameters:
1106+
- name: database-name
1107+
in: path
1108+
required: true
1109+
example: _system
1110+
description: |
1111+
The name of a database. Which database you use doesn't matter as long
1112+
as the user account you authenticate with has at least read access
1113+
to this database and administrate access to the `_system` database.
1114+
If `--log.recording-api-enabled` is set to `jwt`, you need to use
1115+
a superuser token to access the endpoint.
1116+
schema:
1117+
type: string
1118+
responses:
1119+
'200':
1120+
description: |
1121+
Returns the recorded AQL queries.
1122+
content:
1123+
application/json:
1124+
schema:
1125+
type: object
1126+
required:
1127+
- error
1128+
- code
1129+
- result
1130+
properties:
1131+
error:
1132+
description: |
1133+
A flag indicating that no error occurred.
1134+
type: boolean
1135+
example: false
1136+
code:
1137+
description: |
1138+
The HTTP response status code.
1139+
type: integer
1140+
example: 200
1141+
result:
1142+
description: |
1143+
The request result.
1144+
type: object
1145+
required:
1146+
- queries
1147+
properties:
1148+
queries:
1149+
description: |
1150+
A list of the recent AQL queries.
1151+
Empty if AQL query recording is disabled.
1152+
type: array
1153+
items:
1154+
type: object
1155+
properties:
1156+
timeStamp:
1157+
description: |
1158+
The date and time of the request in ISO 8601 format.
1159+
type: string
1160+
format: date-time
1161+
query:
1162+
description: |
1163+
The AQL query.
1164+
type: string
1165+
bindVars:
1166+
description: |
1167+
Key/value pairs representing the bind variables.
1168+
type: object
1169+
database:
1170+
description: |
1171+
The database name.
1172+
type: string
1173+
'401':
1174+
description: |
1175+
The user account has insufficient permissions for the selected database.
1176+
content:
1177+
application/json:
1178+
schema:
1179+
type: object
1180+
required:
1181+
- error
1182+
- code
1183+
- errorNum
1184+
- errorMessage
1185+
properties:
1186+
error:
1187+
description: |
1188+
A flag indicating that an error occurred.
1189+
type: boolean
1190+
example: true
1191+
code:
1192+
description: |
1193+
The HTTP response status code.
1194+
type: integer
1195+
example: 401
1196+
errorNum:
1197+
description: |
1198+
ArangoDB error number for the error that occurred.
1199+
type: integer
1200+
errorMessage:
1201+
description: |
1202+
A descriptive error message.
1203+
type: string
1204+
'403':
1205+
description: |
1206+
The recording API has been disabled.
1207+
content:
1208+
application/json:
1209+
schema:
1210+
type: object
1211+
required:
1212+
- error
1213+
- code
1214+
- errorNum
1215+
- errorMessage
1216+
properties:
1217+
error:
1218+
description: |
1219+
A flag indicating that an error occurred.
1220+
type: boolean
1221+
example: true
1222+
code:
1223+
description: |
1224+
The HTTP response status code.
1225+
type: integer
1226+
example: 403
1227+
errorNum:
1228+
description: |
1229+
ArangoDB error number for the error that occurred.
1230+
type: integer
1231+
errorMessage:
1232+
description: |
1233+
A descriptive error message.
1234+
type: string
1235+
'501':
1236+
description: |
1237+
The method has not been called on a Coordinator or single server.
1238+
content:
1239+
application/json:
1240+
schema:
1241+
type: object
1242+
required:
1243+
- error
1244+
- code
1245+
- errorNum
1246+
- errorMessage
1247+
properties:
1248+
error:
1249+
description: |
1250+
A flag indicating that an error occurred.
1251+
type: boolean
1252+
example: true
1253+
code:
1254+
description: |
1255+
The HTTP response status code.
1256+
type: integer
1257+
example: 501
1258+
errorNum:
1259+
description: |
1260+
ArangoDB error number for the error that occurred.
1261+
type: integer
1262+
errorMessage:
1263+
description: |
1264+
A descriptive error message.
1265+
type: string
1266+
tags:
1267+
- Monitoring
1268+
```
1269+
1270+
{{< comment >}}
1271+
Example not generated because it changes on every run and there can be many internal queries.
1272+
{{< /comment >}}
1273+
1274+
```bash
1275+
curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/server/aql-queries
1276+
```
1277+
1278+
{{< details summary="Show output" >}}
1279+
```bash
1280+
HTTP/1.1 200 OK
1281+
X-Arango-Queue-Time-Seconds: 0.000000
1282+
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
1283+
Expires: 0
1284+
Pragma: no-cache
1285+
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
1286+
Content-Security-Policy: frame-ancestors 'self'; form-action 'self';
1287+
X-Content-Type-Options: nosniff
1288+
Server: ArangoDB
1289+
Connection: Keep-Alive
1290+
Content-Type: application/json; charset=utf-8
1291+
Content-Length: 353
1292+
1293+
{
1294+
"error": false,
1295+
"code": 200,
1296+
"result": {
1297+
"queries": [
1298+
{
1299+
"timeStamp": "2025-07-02T16:33:32Z",
1300+
"query": "FOR s in @@collection FILTER s.time < @start RETURN s._key",
1301+
"database": "_system",
1302+
"bindVars": {
1303+
"@collection": "_statistics",
1304+
"start": 1751470412.3836362
1305+
}
1306+
},
1307+
{
1308+
"timeStamp": "2025-07-02T16:26:01Z",
1309+
"query": "FOR doc IN coll RETURN doc",
1310+
"database": "_system",
1311+
"bindVars": {}
1312+
}
1313+
]
1314+
}
1315+
}
1316+
```
1317+
{{< /details >}}

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,17 @@ is for debugging purposes.
309309
See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
310310
for details.
311311

312+
#### AQL query recording
313+
314+
<small>Introduced in: v3.12.6</small>
315+
316+
A new `/_admin/server/aql-queries` endpoint has been added to let you retrieve a
317+
list of the most recent AQL queries with a timestamp and information about the
318+
submitted queries. This feature is for debugging purposes.
319+
320+
See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-aql-queries)
321+
for details.
322+
312323
#### Access tokens
313324

314325
<small>Introduced in: v3.12.5</small>

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

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2252,9 +2252,9 @@ is for debugging purposes.
22522252
You can configure the memory limit for this feature with the following startup option:
22532253

22542254
- `--server.api-recording-memory-limit`:
2255-
Size limit for the list of API call records (default: `25600000`).
2255+
Size limit for the list of API call records (default: `26214400`).
22562256

2257-
This means that 25 MB of memory is reserved by default.
2257+
This means that 25 MiB of memory is reserved by default.
22582258

22592259
API call recording is enabled by default but you can disable it via the new
22602260
`--server.api-call-recording` startup option.
@@ -2273,6 +2273,41 @@ impact of this feature:
22732273
See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls)
22742274
for details.
22752275

2276+
### AQL query recording
2277+
2278+
<small>Introduced in: v3.12.6</small>
2279+
2280+
A new `/_admin/server/aql-queries` endpoint has been added to let you retrieve a
2281+
list of the most recent AQL queries with a timestamp and information about the
2282+
submitted query. This feature is for debugging purposes.
2283+
2284+
You can configure the memory limit for this feature with the following startup option:
2285+
2286+
- `--server.aql-recording-memory-limit`:
2287+
Size limit for the list of AQL query records (default: `26214400` bytes)
2288+
2289+
This means that 25 MiB of memory is reserved by default.
2290+
2291+
AQL query recording is enabled by default but you can disable it via the new
2292+
`--server.aql-query-recording` startup option.
2293+
2294+
This and the `/_admin/server/api-calls` endpoint are referred to as the
2295+
recording API, which exposes the recorded API calls and AQL queries. It is
2296+
enabled by default. Users with administrative access to the `_system` database
2297+
can call the endpoints. You can further restrict the access to only the
2298+
superuser by setting `--log.recording-api-enabled` to `jwt`, or disable the
2299+
endpoints altogether by setting the option to `false`.
2300+
2301+
A metric has been added for the time spent on AQL query recording to track the
2302+
impact of this feature:
2303+
2304+
| Label | Description |
2305+
|:------|:------------|
2306+
| `arangodb_aql_recording_call_time` | Execution time histogram for AQL recording calls in nanoseconds. |
2307+
2308+
See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-aql-queries)
2309+
for details.
2310+
22762311
### Access tokens
22772312

22782313
<small>Introduced in: v3.12.5</small>

0 commit comments

Comments
 (0)