From bd36857821d5575d853e4bbcd4b8b3fbb019a397 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Wed, 2 Jul 2025 19:23:11 +0200 Subject: [PATCH 1/5] AQL query recording API --- .../3.12/develop/http-api/monitoring/logs.md | 174 +++++++++++++++++- .../version-3.12/api-changes-in-3-12.md | 11 ++ .../version-3.12/whats-new-in-3-12.md | 32 +++- 3 files changed, 214 insertions(+), 3 deletions(-) diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index 64bef4afa0..c7e69fce5f 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/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 >}} diff --git a/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md index aad7f29cec..ada659b652 100644 --- a/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md +++ b/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 + +Introduced in: v3.12.6 + +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 diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md index 77b8c26bb2..6a4dbe11f1 100644 --- a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/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 + +Introduced in: v3.12.6 + +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 From 7dbaa22092dff20cf5ce76987ef5983c6705ef62 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 4 Jul 2025 14:38:27 +0200 Subject: [PATCH 2/5] Fix text about startup option, add more status codes --- .../3.12/develop/http-api/monitoring/logs.md | 154 ++++++++- .../3.13/develop/http-api/monitoring/logs.md | 318 +++++++++++++++++- 2 files changed, 452 insertions(+), 20 deletions(-) diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index c7e69fce5f..359aa08ac6 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/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,14 +848,17 @@ paths: operationId: getRecentApiCalls description: | Get a list of the most recent requests with a timestamp and the endpoint. - This feature is for debugging purposes. + This feature is for debugging purposes. You can control how much memory is used to record API calls with the - `--server.memory-per-api-call-list` and `--server.number-of-api-call-lists` - startup options. + `--server.api-recording-memory-limit` startup option. - You can disable API call recording via the `--server.api-call-recording` - startup option. The endpoint returns an empty list of calls in this case. + 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 + `--server.api-call-recording` startup option. + The endpoint returns an empty list of queries if turned off. parameters: - name: database-name in: path @@ -872,7 +875,7 @@ paths: responses: '200': description: | - The + Returns the recorded API calls. content: application/json: schema: @@ -955,6 +958,68 @@ paths: 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 ``` @@ -1020,9 +1085,12 @@ paths: 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. + 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 @@ -1039,7 +1107,7 @@ paths: responses: '200': description: | - The + Returns the recorded AQL queries. content: application/json: schema: @@ -1069,7 +1137,7 @@ paths: queries: description: | A list of the recent AQL queries. - Empty if AQL query and API call recording is disabled. + Empty if AQL query recording is disabled. type: array items: type: object @@ -1122,6 +1190,68 @@ paths: 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 ``` diff --git a/site/content/3.13/develop/http-api/monitoring/logs.md b/site/content/3.13/develop/http-api/monitoring/logs.md index 64bef4afa0..359aa08ac6 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/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,14 +848,17 @@ paths: operationId: getRecentApiCalls description: | Get a list of the most recent requests with a timestamp and the endpoint. - This feature is for debugging purposes. + This feature is for debugging purposes. You can control how much memory is used to record API calls with the - `--server.memory-per-api-call-list` and `--server.number-of-api-call-lists` - startup options. + `--server.api-recording-memory-limit` startup option. + + You can disable this and the `/_admin/server/aql-queries` endpoint + with the `--log.recording-api-enabled` startup option. - You can disable API call recording via the `--server.api-call-recording` - startup option. The endpoint returns an empty list of calls in this case. + Whether API calls are recorded is independently controlled by the + `--server.api-call-recording` startup option. + The endpoint returns an empty list of queries if turned off. parameters: - name: database-name in: path @@ -864,13 +867,15 @@ 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: '200': description: | - The + Returns the recorded API calls. content: application/json: schema: @@ -953,6 +958,68 @@ paths: 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 ``` @@ -1002,3 +1069,238 @@ 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 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 + 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 + '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: 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 >}} From 2d3acc9951cc18d095a4128ffb7c98629341f620 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 4 Jul 2025 15:12:31 +0200 Subject: [PATCH 3/5] Rework release notes, adjust attribute names --- .../3.12/develop/http-api/monitoring/logs.md | 14 +++--- .../version-3.12/whats-new-in-3-12.md | 34 ++++++++----- .../3.13/develop/http-api/monitoring/logs.md | 14 +++--- .../version-3.12/api-changes-in-3-12.md | 11 ++++ .../version-3.12/whats-new-in-3-12.md | 50 ++++++++++++++++--- 5 files changed, 89 insertions(+), 34 deletions(-) diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index 359aa08ac6..3a648b781c 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/site/content/3.12/develop/http-api/monitoring/logs.md @@ -1147,11 +1147,11 @@ paths: The date and time of the request in ISO 8601 format. type: string format: date-time - queryString: + query: description: | The AQL query. type: string - bindParameters: + bindVars: description: | Key/value pairs representing the bind variables. type: object @@ -1277,7 +1277,7 @@ X-Content-Type-Options: nosniff Server: ArangoDB Connection: Keep-Alive Content-Type: application/json; charset=utf-8 -Content-Length: 377 +Content-Length: 353 { "error": false, @@ -1286,18 +1286,18 @@ Content-Length: 377 "queries": [ { "timeStamp": "2025-07-02T16:33:32Z", - "queryString": "FOR s in @@collection FILTER s.time < @start RETURN s._key", + "query": "FOR s in @@collection FILTER s.time < @start RETURN s._key", "database": "_system", - "bindParameters": { + "bindVars": { "@collection": "_statistics", "start": 1751470412.3836362 } }, { "timeStamp": "2025-07-02T16:26:01Z", - "queryString": "FOR doc IN coll RETURN doc", + "query": "FOR doc IN coll RETURN doc", "database": "_system", - "bindParameters": {} + "bindVars": {} } ] } diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md index 6a4dbe11f1..9319b37d6f 100644 --- a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md @@ -2167,18 +2167,20 @@ A new `/_admin/server/api-calls` endpoint has been added to let you retrieve a list of the most recent requests with a timestamp and the endpoint. This feature is for debugging purposes. -You can configure the memory limit for this feature with the following startup options: +You can configure the memory limit for this feature with the following startup option: -- `--server.number-of-api-call-lists`: - The size of the ring buffer for API call record lists (default: `256`). -- `--server.memory-per-api-call-list`: - The amount of memory used for a single API call record list (default: `100000` bytes) +- `--server.api-recording-memory-limit`: + Size limit for the list of API call records (default: `26214400`). -This means that approximately 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. +The `/_admin/server/api-calls` endpoint exposes the recorded API calls. +It is enabled by default. You can disable it altogether by setting the new +`--log.recording-api-enabled` startup option to `false`. + A metric has been added for the time spent on API call recording to track the impact of this feature: @@ -2188,6 +2190,7 @@ 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 Introduced in: v3.12.6 @@ -2198,15 +2201,20 @@ 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) +- `--server.aql-recording-memory-limit`: + Size limit for the list of AQL query records (default: `26214400` bytes) -This means that approximately 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 -`--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. +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: diff --git a/site/content/3.13/develop/http-api/monitoring/logs.md b/site/content/3.13/develop/http-api/monitoring/logs.md index 359aa08ac6..3a648b781c 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/develop/http-api/monitoring/logs.md @@ -1147,11 +1147,11 @@ paths: The date and time of the request in ISO 8601 format. type: string format: date-time - queryString: + query: description: | The AQL query. type: string - bindParameters: + bindVars: description: | Key/value pairs representing the bind variables. type: object @@ -1277,7 +1277,7 @@ X-Content-Type-Options: nosniff Server: ArangoDB Connection: Keep-Alive Content-Type: application/json; charset=utf-8 -Content-Length: 377 +Content-Length: 353 { "error": false, @@ -1286,18 +1286,18 @@ Content-Length: 377 "queries": [ { "timeStamp": "2025-07-02T16:33:32Z", - "queryString": "FOR s in @@collection FILTER s.time < @start RETURN s._key", + "query": "FOR s in @@collection FILTER s.time < @start RETURN s._key", "database": "_system", - "bindParameters": { + "bindVars": { "@collection": "_statistics", "start": 1751470412.3836362 } }, { "timeStamp": "2025-07-02T16:26:01Z", - "queryString": "FOR doc IN coll RETURN doc", + "query": "FOR doc IN coll RETURN doc", "database": "_system", - "bindParameters": {} + "bindVars": {} } ] } diff --git a/site/content/3.13/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/3.13/release-notes/version-3.12/api-changes-in-3-12.md index aad7f29cec..ada659b652 100644 --- a/site/content/3.13/release-notes/version-3.12/api-changes-in-3-12.md +++ b/site/content/3.13/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 + +Introduced in: v3.12.6 + +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 diff --git a/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md index 77b8c26bb2..9319b37d6f 100644 --- a/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md @@ -2167,19 +2167,20 @@ A new `/_admin/server/api-calls` endpoint has been added to let you retrieve a list of the most recent requests with a timestamp and the endpoint. This feature is for debugging purposes. -You can configure the memory limit for this feature with the following startup options: +You can configure the memory limit for this feature with the following startup option: -- `--server.number-of-api-call-lists`: - The size of the ring buffer for API call record lists (default: `256`). -- `--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. +- `--server.api-recording-memory-limit`: + Size limit for the list of API call records (default: `26214400`). +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. +The `/_admin/server/api-calls` endpoint exposes the recorded API calls. +It is enabled by default. You can disable it altogether by setting the new +`--log.recording-api-enabled` startup option to `false`. + A metric has been added for the time spent on API call recording to track the impact of this feature: @@ -2190,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 + +Introduced in: v3.12.6 + +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 From 63b4e8b493d288b4b676c7a99420eefbcebe79c3 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 4 Jul 2025 15:32:38 +0200 Subject: [PATCH 4/5] Fix copy-paste mistake --- site/content/3.12/develop/http-api/monitoring/logs.md | 2 +- site/content/3.13/develop/http-api/monitoring/logs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index 3a648b781c..b689cbe983 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/site/content/3.12/develop/http-api/monitoring/logs.md @@ -858,7 +858,7 @@ paths: Whether API calls are recorded is independently controlled by the `--server.api-call-recording` startup option. - The endpoint returns an empty list of queries if turned off. + The endpoint returns an empty list of calls if turned off. parameters: - name: database-name in: path diff --git a/site/content/3.13/develop/http-api/monitoring/logs.md b/site/content/3.13/develop/http-api/monitoring/logs.md index 3a648b781c..b689cbe983 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/develop/http-api/monitoring/logs.md @@ -858,7 +858,7 @@ paths: Whether API calls are recorded is independently controlled by the `--server.api-call-recording` startup option. - The endpoint returns an empty list of queries if turned off. + The endpoint returns an empty list of calls if turned off. parameters: - name: database-name in: path From 872694ee37024be62fe754a9a6d4bdf15b783add Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Sat, 5 Jul 2025 11:52:16 +0200 Subject: [PATCH 5/5] Per Coordinator recording in clusters --- site/content/3.12/develop/http-api/monitoring/logs.md | 7 +++++-- site/content/3.13/develop/http-api/monitoring/logs.md | 7 +++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index 807c9988a3..b71947c05c 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/site/content/3.12/develop/http-api/monitoring/logs.md @@ -848,6 +848,8 @@ 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 @@ -1079,8 +1081,9 @@ paths: 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. + 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. diff --git a/site/content/3.13/develop/http-api/monitoring/logs.md b/site/content/3.13/develop/http-api/monitoring/logs.md index 807c9988a3..b71947c05c 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/develop/http-api/monitoring/logs.md @@ -848,6 +848,8 @@ 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 @@ -1079,8 +1081,9 @@ paths: 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. + 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.