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 95869c2fe0..472d7f798b 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/site/content/3.12/develop/http-api/monitoring/logs.md @@ -840,3 +840,167 @@ paths: tags: - Monitoring ``` + +## Get recent API calls + +```openapi +paths: + /_db/{database-name}/_admin/server/api-calls: + get: + operationId: getRecentApiCalls + description: | + Get a list of the most recent requests with a timestamp and the endpoint. + 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. + + 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. + 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. + 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: + - calls + properties: + calls: + description: | + A list of the recent API calls. Empty if 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 + requestType: + description: | + The HTTP request method. + type: string + enum: [get, patch, put, delete, head] + path: + description: | + The HTTP request path excluding the database prefix (`/_db/`). + type: string + 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 returns up to 25MB of data. +{{< /comment >}} + +```bash +curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/server/api-calls +``` + +{{< 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: 257 + +{ + "error": false, + "code": 200, + "result": { + "calls": [ + { + "timeStamp": "2025-06-11T14:41:53Z", + "requestType": "GET", + "path": "/_admin/server/api-calls", + "database": "_system" + }, + { + "timeStamp": "2025-06-11T14:41:51Z", + "requestType": "GET", + "path": "/_api/version", + "database": "myDB" + } + ] + } +} +``` +{{< /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 c93182bf30..0b0ab99541 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 @@ -298,6 +298,17 @@ for AQL execution plans. Query plan caching works on a per-database basis. See [HTTP interface for the query plan cache](../../develop/http-api/queries/aql-query-plan-cache.md) for details. +#### API call recording + +Introduced in: v3.12.5 + +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. + +See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls) +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 39ffd8435e..007c6a911b 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 @@ -2085,6 +2085,37 @@ DB-Servers in a cluster has been added: |:------|:------------| | `arangodb_vocbase_transactions_lost_subordinates_total` | Counts the number of lost subordinate transactions on database servers. | +### API call recording + +Introduced in: v3.12.5 + +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: + +- `--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. + + +API call recording is enabled by default but you can disable it via the new +`--server.api-call-recording` startup option. + +A metric has been added for the time spent on API call recording to track the +impact of this feature: + +| Label | Description | +|:------|:------------| +| `arangodb_api_recording_call_time` | Execution time histogram for API recording calls in nanoseconds. | + +See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls) +for details. + ## Client tools ### Protocol aliases for endpoints 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 95869c2fe0..472d7f798b 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/develop/http-api/monitoring/logs.md @@ -840,3 +840,167 @@ paths: tags: - Monitoring ``` + +## Get recent API calls + +```openapi +paths: + /_db/{database-name}/_admin/server/api-calls: + get: + operationId: getRecentApiCalls + description: | + Get a list of the most recent requests with a timestamp and the endpoint. + 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. + + 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. + 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. + 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: + - calls + properties: + calls: + description: | + A list of the recent API calls. Empty if 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 + requestType: + description: | + The HTTP request method. + type: string + enum: [get, patch, put, delete, head] + path: + description: | + The HTTP request path excluding the database prefix (`/_db/`). + type: string + 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 returns up to 25MB of data. +{{< /comment >}} + +```bash +curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/server/api-calls +``` + +{{< 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: 257 + +{ + "error": false, + "code": 200, + "result": { + "calls": [ + { + "timeStamp": "2025-06-11T14:41:53Z", + "requestType": "GET", + "path": "/_admin/server/api-calls", + "database": "_system" + }, + { + "timeStamp": "2025-06-11T14:41:51Z", + "requestType": "GET", + "path": "/_api/version", + "database": "myDB" + } + ] + } +} +``` +{{< /expand >}} 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 c93182bf30..0b0ab99541 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 @@ -298,6 +298,17 @@ for AQL execution plans. Query plan caching works on a per-database basis. See [HTTP interface for the query plan cache](../../develop/http-api/queries/aql-query-plan-cache.md) for details. +#### API call recording + +Introduced in: v3.12.5 + +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. + +See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls) +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 39ffd8435e..007c6a911b 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 @@ -2085,6 +2085,37 @@ DB-Servers in a cluster has been added: |:------|:------------| | `arangodb_vocbase_transactions_lost_subordinates_total` | Counts the number of lost subordinate transactions on database servers. | +### API call recording + +Introduced in: v3.12.5 + +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: + +- `--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. + + +API call recording is enabled by default but you can disable it via the new +`--server.api-call-recording` startup option. + +A metric has been added for the time spent on API call recording to track the +impact of this feature: + +| Label | Description | +|:------|:------------| +| `arangodb_api_recording_call_time` | Execution time histogram for API recording calls in nanoseconds. | + +See [HTTP interface for server logs](../../develop/http-api/monitoring/logs.md#get-recent-api-calls) +for details. + ## Client tools ### Protocol aliases for endpoints