Skip to content
This repository was archived by the owner on Dec 13, 2023. It is now read-only.

Commit 609b298

Browse files
neunhoefneunhoef
authored
Soft coordinator shutdown documentation (#716)
* Monkey-patch in the latest locally-generated examples (3.9) * main branch contains 3.7 examples, 3.8 not relevant for 3.8.0 release
1 parent b5b3b91 commit 609b298

File tree

5 files changed

+187
-3
lines changed

5 files changed

+187
-3
lines changed

‎3.7/http/miscellaneous-functions.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ This is an overview of ArangoDB's HTTP interface for miscellaneous functions.
2323
<!-- lib/Admin/RestShutdownHandler.cpp -->
2424
{% docublock delete_api_shutdown %}
2525

26+
<!-- lib/Admin/RestShutdownHandler.cpp -->
27+
{% docublock get_api_shutdown %}
28+
2629
<!-- js/actions/api-system.js -->
2730
{% docublock post_admin_execute %}
2831

‎3.8/http/miscellaneous-functions.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ This is an overview of ArangoDB's HTTP interface for miscellaneous functions.
2323
<!-- lib/Admin/RestShutdownHandler.cpp -->
2424
{% docublock delete_api_shutdown %}
2525

26+
<!-- lib/Admin/RestShutdownHandler.cpp -->
27+
{% docublock get_api_shutdown %}
28+
2629
<!-- js/actions/api-system.js -->
2730
{% docublock post_admin_execute %}
2831

‎3.9/generated/allComments.txt

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34630,8 +34630,35 @@ This API will return HTTP 200 if everything is ok
3463034630

3463134631
@RESTHEADER{DELETE /_admin/shutdown, Initiate shutdown sequence, RestShutdownHandler}
3463234632

34633+
@RESTQUERYPARAMETERS
34634+
34635+
@RESTQUERYPARAM{soft,boolean,optional}
34636+
<small>Introduced in: v3.7.12, v3.8.1, v3.9.0</small>
34637+
34638+
If set to `true`, this initiates a soft shutdown. This is only available
34639+
on Coordinators. When issued, the Coordinator tracks a number of ongoing
34640+
operations, waits until all have finished, and then shuts itself down
34641+
normally. In the meantime, new operations of these types are no longer
34642+
accepted and a 503 response is sent instead. However, further requests
34643+
to finish the ongoing operations are allowed. This feature can be used
34644+
to make restart operations of Coordinators less intrusive for clients.
34645+
34646+
The following types of operations are tracked:
34647+
34648+
- AQL cursors (in particular streaming cursors)
34649+
- Transactions (in particular stream transactions)
34650+
- Pregel runs (conducted by this Coordinator)
34651+
- Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header
34652+
- Finished asynchronous requests, whose result has not yet been
34653+
collected
34654+
- Queued low priority requests (most normal requests)
34655+
- Ongoing low priority requests
34656+
34657+
Note that the latter two are tracked but not prevented from being
34658+
started, to allow for finishing operations.
34659+
3463334660
@RESTDESCRIPTION
34634-
This call initiates a clean shutdown sequence. Requires administrive privileges
34661+
This call initiates a clean shutdown sequence. Requires administrive privileges.
3463534662

3463634663
@RESTRETURNCODES
3463734664

@@ -34641,6 +34668,68 @@ is returned in all cases, `OK` will be returned in the result buffer on success.
3464134668
@endDocuBlock
3464234669

3464334670

34671+
<!-- filename: /work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md -->
34672+
@startDocuBlock get_api_shutdown
34673+
34674+
@brief query progress of soft shutdown process
34675+
34676+
@RESTHEADER{GET /_admin/shutdown, Query progress of soft shutdown process, RestGetShutdownHandler}
34677+
34678+
@RESTDESCRIPTION
34679+
<small>Introduced in: v3.7.12, v3.8.1, v3.9.0</small>
34680+
34681+
This call reports progress about a soft Coordinator shutdown (see
34682+
documentation of `DELETE /_admin/shutdown?soft=true`).
34683+
In this case, the following types of operations are tracked:
34684+
34685+
- AQL cursors (in particular streaming cursors)
34686+
- Transactions (in particular stream transactions)
34687+
- Pregel runs (conducted by this Coordinator)
34688+
- Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header
34689+
- Finished asynchronous requests, whose result has not yet been
34690+
collected
34691+
- Queued low priority requests (most normal requests)
34692+
- Ongoing low priority requests
34693+
34694+
This API is only available on Coordinators.
34695+
34696+
@RESTRETURNCODES
34697+
34698+
@RESTRETURNCODE{200}
34699+
The response indicates the fact that a soft shutdown is ongoing and the
34700+
number of active operations of the various types. Once all numbers have gone
34701+
to 0, the flag `allClear` is set and the Coordinator shuts down automatically.
34702+
34703+
@RESTREPLYBODY{softShutdownOngoing,boolean,required,}
34704+
Whether a soft shutdown of the Coordinator is in progress.
34705+
34706+
@RESTREPLYBODY{AQLcursors,number,required,}
34707+
Number of AQL cursors that are still active.
34708+
34709+
@RESTREPLYBODY{transactions,number,required,}
34710+
Number of ongoing transactions.
34711+
34712+
@RESTREPLYBODY{pendingJobs,number,required,}
34713+
Number of ongoing asynchronous requests.
34714+
34715+
@RESTREPLYBODY{doneJobs,number,required,}
34716+
Number of finished asynchronous requests, whose result has not yet been collected.
34717+
34718+
@RESTREPLYBODY{pregelConductors,number,required,}
34719+
Number of ongoing Pregel jobs.
34720+
34721+
@RESTREPLYBODY{lowPrioOngoingRequests,number,required,}
34722+
Number of queued low priority requests.
34723+
34724+
@RESTREPLYBODY{lowPrioQueuedRequests,number,required,}
34725+
Number of ongoing low priority requests.
34726+
34727+
@RESTREPLYBODY{allClear,boolean,required,}
34728+
Whether all active operations finished.
34729+
34730+
@endDocuBlock
34731+
34732+
3464434733
<!-- filename: /work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/post_admin_server_jwt.md -->
3464534734
@startDocuBlock post_admin_server_jwt
3464634735

‎3.9/generated/api-docs.json

Lines changed: 88 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3694,6 +3694,60 @@
36943694
"type": "object",
36953695
"x-filename": "/work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/get_api_return.md"
36963696
},
3697+
"get_api_shutdown_rc_200": {
3698+
"properties": {
3699+
"AQLcursors": {
3700+
"description": "Number of AQL cursors that are still active.\n\n",
3701+
"format": "",
3702+
"type": "number"
3703+
},
3704+
"allClear": {
3705+
"description": "Whether all active operations finished.\n\n\n",
3706+
"format": "",
3707+
"type": "boolean"
3708+
},
3709+
"doneJobs": {
3710+
"description": "Number of finished asynchronous requests, whose result has not yet been collected.\n\n",
3711+
"format": "",
3712+
"type": "number"
3713+
},
3714+
"lowPrioOngoingRequests": {
3715+
"description": "Number of queued low priority requests.\n\n",
3716+
"format": "",
3717+
"type": "number"
3718+
},
3719+
"lowPrioQueuedRequests": {
3720+
"description": "Number of ongoing low priority requests.\n\n",
3721+
"format": "",
3722+
"type": "number"
3723+
},
3724+
"pendingJobs": {
3725+
"description": "Number of ongoing asynchronous requests.\n\n",
3726+
"format": "",
3727+
"type": "number"
3728+
},
3729+
"pregelConductors": {
3730+
"description": "Number of ongoing Pregel jobs.\n\n",
3731+
"format": "",
3732+
"type": "number"
3733+
},
3734+
"softShutdownOngoing": {
3735+
"description": "Whether a soft shutdown of the Coordinator is in progress.\n\n",
3736+
"format": "",
3737+
"type": "boolean"
3738+
},
3739+
"transactions": {
3740+
"description": "Number of ongoing transactions.\n\n",
3741+
"format": "",
3742+
"type": "number"
3743+
}
3744+
},
3745+
"required": [
3746+
"softShutdownOngoing"
3747+
],
3748+
"type": "object",
3749+
"x-filename": "/home/simran/oskar2/work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md"
3750+
},
36973751
"get_api_tasks_all_rc_200": {
36983752
"description": "a list of all tasks\n\n",
36993753
"items": {
@@ -7124,9 +7178,17 @@
71247178
},
71257179
"/_admin/shutdown": {
71267180
"delete": {
7127-
"description": "\n\nThis call initiates a clean shutdown sequence. Requires administrive privileges\n\n",
7181+
"description": "\n\nThis call initiates a clean shutdown sequence. Requires administrive privileges.\n\n",
71287182
"operationId": "RestShutdownHandler",
7129-
"parameters": [],
7183+
"parameters": [
7184+
{
7185+
"description": "<small>Introduced in: v3.7.12, v3.8.1, v3.9.0</small>\n\nIf set to `true`, this initiates a soft shutdown. This is only available\non Coordinators. When issued, the Coordinator tracks a number of ongoing\noperations, waits until all have finished, and then shuts itself down\nnormally. In the meantime, new operations of these types are no longer\naccepted and a 503 response is sent instead. However, further requests\nto finish the ongoing operations are allowed. This feature can be used\nto make restart operations of Coordinators less intrusive for clients.\n\nThe following types of operations are tracked:\n\n - AQL cursors (in particular streaming cursors)\n - Transactions (in particular stream transactions)\n - Pregel runs (conducted by this Coordinator)\n - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header\n - Finished asynchronous requests, whose result has not yet been\n collected\n - Queued low priority requests (most normal requests)\n - Ongoing low priority requests\n\nNote that the latter two are tracked but not prevented from being\nstarted, to allow for finishing operations.\n\n",
7186+
"in": "query",
7187+
"name": "soft",
7188+
"required": false,
7189+
"type": "boolean"
7190+
}
7191+
],
71307192
"responses": {
71317193
"200": {
71327194
"description": "is returned in all cases, `OK` will be returned in the result buffer on success.\n\n\n"
@@ -7139,6 +7201,30 @@
71397201
"x-examples": [],
71407202
"x-filename": "/work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md",
71417203
"x-hints": ""
7204+
},
7205+
"get": {
7206+
"description": "\n\n<small>Introduced in: v3.7.12, v3.8.1, v3.9.0</small>\n\nThis call reports progress about a soft Coordinator shutdown (see\ndocumentation of `DELETE /_admin/shutdown?soft=true`).\nIn this case, the following types of operations are tracked:\n\n - AQL cursors (in particular streaming cursors)\n - Transactions (in particular stream transactions)\n - Pregel runs (conducted by this Coordinator)\n - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header\n - Finished asynchronous requests, whose result has not yet been\n collected\n - Queued low priority requests (most normal requests)\n - Ongoing low priority requests\n\nThis API is only available on Coordinators.\n\n\n**HTTP 200**\n*A json document with these Properties is returned:*\n\nThe response indicates the fact that a soft shutdown is ongoing and the\nnumber of active operations of the various types. Once all numbers have gone\nto 0, the flag `allClear` is set and the Coordinator shuts down automatically.\n\n- **lowPrioOngoingRequests**: Number of queued low priority requests.\n- **transactions**: Number of ongoing transactions.\n- **pendingJobs**: Number of ongoing asynchronous requests.\n- **pregelConductors**: Number of ongoing Pregel jobs.\n- **lowPrioQueuedRequests**: Number of ongoing low priority requests.\n- **AQLcursors**: Number of AQL cursors that are still active.\n- **softShutdownOngoing**: Whether a soft shutdown of the Coordinator is in progress.\n- **doneJobs**: Number of finished asynchronous requests, whose result has not yet been collected.\n- **allClear**: Whether all active operations finished.\n\n",
7207+
"operationId": "RestGetShutdownHandler",
7208+
"parameters": [],
7209+
"produces": [
7210+
"application/json"
7211+
],
7212+
"responses": {
7213+
"200": {
7214+
"description": "The response indicates the fact that a soft shutdown is ongoing and the\nnumber of active operations of the various types. Once all numbers have gone\nto 0, the flag `allClear` is set and the Coordinator shuts down automatically.\n\n",
7215+
"schema": {
7216+
"$ref": "#/definitions/get_api_shutdown_rc_200"
7217+
},
7218+
"x-description-offset": 747
7219+
}
7220+
},
7221+
"summary": "Query progress of soft shutdown process",
7222+
"tags": [
7223+
"Administration"
7224+
],
7225+
"x-examples": [],
7226+
"x-filename": "/work/ArangoDB/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md",
7227+
"x-hints": ""
71427228
}
71437229
},
71447230
"/_admin/statistics": {

‎3.9/http/miscellaneous-functions.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ This is an overview of ArangoDB's HTTP interface for miscellaneous functions.
2323
<!-- lib/Admin/RestShutdownHandler.cpp -->
2424
{% docublock delete_api_shutdown %}
2525

26+
<!-- lib/Admin/RestShutdownHandler.cpp -->
27+
{% docublock get_api_shutdown %}
28+
2629
<!-- js/actions/api-system.js -->
2730
{% docublock post_admin_execute %}
2831

0 commit comments

Comments
 (0)