From feb99c4d04deb8f88c7c08c35d36739d3be71d8c Mon Sep 17 00:00:00 2001 From: Max Neunhoeffer Date: Fri, 11 Jun 2021 08:50:41 +0200 Subject: [PATCH 1/8] Add documentation for soft coordinator shutdown. --- .../Administration/delete_api_shutdown.md | 27 ++++++++++- .../Rest/Administration/get_api_shutdown.md | 48 +++++++++++++++++++ 2 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md diff --git a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md index 9fbdf2718ee7..c2da5f433e02 100644 --- a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md @@ -4,8 +4,33 @@ @RESTHEADER{DELETE /_admin/shutdown, Initiate shutdown sequence, RestShutdownHandler} +@RESTQUERYPARAMETERS + +@RESTQUERYPARAM{soft,boolean,optional} +If set to `true`, this initiates a soft shutdown. This is only available +on coordinators. When issued, the coordinator tracks a number of ongoing +operations, waits until all have finished, and then shuts itself down +normally. In the meantime, new operations of these types are no longer +accepted and a 503 response is sent instead. However, further requests +to finish the ongoing operations are allowed. This feature can be used +to make restart operations of coordinators less intrusive for clients. + +The following types of operations are tracked: + + - AQL cursors (in particular streaming cursors) + - Transactions (in particular streaming transactions) + - Pregel runs (conducted by this coordinator) + - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header + - Finished asynchronous requests, whose result has not yet been + collected + - Queued low priority requests (most normal requests) + - Ongoing low priority requests + +Note that the latter two are tracked but not prevented from being +started, to allow for finishing operations. + @RESTDESCRIPTION -This call initiates a clean shutdown sequence. Requires administrive privileges +This call initiates a clean shutdown sequence. Requires administrive privileges. @RESTRETURNCODES diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md new file mode 100644 index 000000000000..034e94f89e74 --- /dev/null +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -0,0 +1,48 @@ + +@startDocuBlock get_api_shutdown +@brief initiates the shutdown sequence + +@RESTHEADER{GET /_admin/shutdown, Query progress of soft shutdown process, RestShutdownHandler} + +@RESTDESCRIPTION +This call reports progress about a soft coordinator shutdown (see +documentation of `DELETE /_admin/shutdown?soft=true`. +In this case, the following types of operations are tracked: + + - AQL cursors (in particular streaming cursors) + - Transactions (in particular streaming transactions) + - Pregel runs (conducted by this coordinator) + - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header + - Finished asynchronous requests, whose result has not yet been + collected + - Queued low priority requests (most normal requests) + - Ongoing low priority requests + +This call returns a JSON object of the following shape, indicating the +fact that a soft shutdown is ongoing and the number of active operations +of the various types: + +```json +{ + "softShutdownOngoing" : true, + "AQLcursors" : 0, + "transactions" : 1, + "pendingJobs" : 1, + "doneJobs" : 0, + "pregelConductors" : 0, + "lowPrioOngoingRequests" : 1, + "lowPrioQueuedRequests" : 0, + "allClear" : false +} +``` + +Once all numbers have gone to 0, the flag `allClear` is set and the +coordinator shuts down automatically. This API is not available on +DBServers and Agents. + +@RESTRETURNCODES + +@RESTRETURNCODE{200} +is returned in all cases, the above JSON object is in the body. + +@endDocuBlock From 67a463931f9ad3623fc04b88401620d6c9bcae99 Mon Sep 17 00:00:00 2001 From: Max Neunhoeffer Date: Fri, 11 Jun 2021 10:13:53 +0200 Subject: [PATCH 2/8] Fix a typo. --- .../DocuBlocks/Rest/Administration/get_api_shutdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index 034e94f89e74..ca97c4e72afc 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -6,7 +6,7 @@ @RESTDESCRIPTION This call reports progress about a soft coordinator shutdown (see -documentation of `DELETE /_admin/shutdown?soft=true`. +documentation of `DELETE /_admin/shutdown?soft=true`). In this case, the following types of operations are tracked: - AQL cursors (in particular streaming cursors) From 74e0f38aabe7952e8368c1fb2d05300eff542800 Mon Sep 17 00:00:00 2001 From: Max Neunhoeffer Date: Mon, 14 Jun 2021 13:43:19 +0200 Subject: [PATCH 3/8] Add introduced in. --- .../DocuBlocks/Rest/Administration/delete_api_shutdown.md | 3 +++ .../DocuBlocks/Rest/Administration/get_api_shutdown.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md index c2da5f433e02..ad44a4034635 100644 --- a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md @@ -29,6 +29,9 @@ The following types of operations are tracked: Note that the latter two are tracked but not prevented from being started, to allow for finishing operations. +This query parameter was introduced in 3.7.12, 3.8.1 and all versions +greater or equal than 3.9. + @RESTDESCRIPTION This call initiates a clean shutdown sequence. Requires administrive privileges. diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index ca97c4e72afc..5b93b7e5b963 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -40,6 +40,9 @@ Once all numbers have gone to 0, the flag `allClear` is set and the coordinator shuts down automatically. This API is not available on DBServers and Agents. +This API call was introduced in 3.7.12, 3.8.1 and all versions greater +or equal to 3.9. + @RESTRETURNCODES @RESTRETURNCODE{200} From 25c65d620d0b1c5fd5aa2dca8fc7587917092b43 Mon Sep 17 00:00:00 2001 From: Simran Date: Wed, 30 Jun 2021 15:55:56 +0200 Subject: [PATCH 4/8] Apply suggestions from code review --- .../Rest/Administration/get_api_shutdown.md | 41 +++++++++++++++---- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index 5b93b7e5b963..f11e456af64b 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -5,13 +5,15 @@ @RESTHEADER{GET /_admin/shutdown, Query progress of soft shutdown process, RestShutdownHandler} @RESTDESCRIPTION -This call reports progress about a soft coordinator shutdown (see +Introduced in: v3.7.12, v3.8.1, v3.9.0 + +This call reports progress about a soft Coordinator shutdown (see documentation of `DELETE /_admin/shutdown?soft=true`). In this case, the following types of operations are tracked: - AQL cursors (in particular streaming cursors) - - Transactions (in particular streaming transactions) - - Pregel runs (conducted by this coordinator) + - Transactions (in particular stream transactions) + - Pregel runs (conducted by this Coordinator) - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header - Finished asynchronous requests, whose result has not yet been collected @@ -37,11 +39,36 @@ of the various types: ``` Once all numbers have gone to 0, the flag `allClear` is set and the -coordinator shuts down automatically. This API is not available on -DBServers and Agents. +Coordinator shuts down automatically. This API is not available on +DB-Servers and Agents. + + +@RESTREPLYBODY{softShutdownOngoing,boolean,required,} +Whether a soft shutdown of the Coordinator is in progress. + +@RESTREPLYBODY{AQLcursors,number,required,} +Number of AQL cursors that are still active. + +@RESTREPLYBODY{transactions,number,required,} +Number of ongoing transactions. + +@RESTREPLYBODY{pendingJobs,number,required,} +Number of ongoing asynchronous requests. + +@RESTREPLYBODY{doneJobs,number,required,} +Number of finished asynchronous requests, whose result has not yet been collected. + +@RESTREPLYBODY{pregelConductors,number,required,} +Number of ongoing Pregel jobs. + +@RESTREPLYBODY{lowPrioOngoingRequests,number,required,} +Number of queued low priority requests. + +@RESTREPLYBODY{lowPrioQueuedRequests,number,required,} +Number of ongoing low priority requests. -This API call was introduced in 3.7.12, 3.8.1 and all versions greater -or equal to 3.9. +@RESTREPLYBODY{allClear,boolean,required,} +Whether all active operations finished. @RESTRETURNCODES From efeb2a39c59ff2d7221ae1e9cf1aa1fc3f66dff0 Mon Sep 17 00:00:00 2001 From: Simran Date: Wed, 30 Jun 2021 18:39:31 +0200 Subject: [PATCH 5/8] Update get_api_shutdown.md --- .../DocuBlocks/Rest/Administration/get_api_shutdown.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index f11e456af64b..c99cae7565e3 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -42,6 +42,10 @@ Once all numbers have gone to 0, the flag `allClear` is set and the Coordinator shuts down automatically. This API is not available on DB-Servers and Agents. +@RESTRETURNCODES + +@RESTRETURNCODE{200} +Returned in all cases. @RESTREPLYBODY{softShutdownOngoing,boolean,required,} Whether a soft shutdown of the Coordinator is in progress. @@ -70,9 +74,4 @@ Number of ongoing low priority requests. @RESTREPLYBODY{allClear,boolean,required,} Whether all active operations finished. -@RESTRETURNCODES - -@RESTRETURNCODE{200} -is returned in all cases, the above JSON object is in the body. - @endDocuBlock From 34f86c8302349ff323f5e46ac8ebeed75e2c5d56 Mon Sep 17 00:00:00 2001 From: Simran Date: Wed, 30 Jun 2021 19:05:54 +0200 Subject: [PATCH 6/8] Update get_api_shutdown.md --- .../Rest/Administration/get_api_shutdown.md | 30 ++++--------------- 1 file changed, 6 insertions(+), 24 deletions(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index c99cae7565e3..017394b399d2 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -1,8 +1,8 @@ @startDocuBlock get_api_shutdown -@brief initiates the shutdown sequence +@brief query progress of soft shutdown process -@RESTHEADER{GET /_admin/shutdown, Query progress of soft shutdown process, RestShutdownHandler} +@RESTHEADER{GET /_admin/shutdown, Query progress of soft shutdown process, RestGetShutdownHandler} @RESTDESCRIPTION Introduced in: v3.7.12, v3.8.1, v3.9.0 @@ -20,32 +20,14 @@ In this case, the following types of operations are tracked: - Queued low priority requests (most normal requests) - Ongoing low priority requests -This call returns a JSON object of the following shape, indicating the -fact that a soft shutdown is ongoing and the number of active operations -of the various types: - -```json -{ - "softShutdownOngoing" : true, - "AQLcursors" : 0, - "transactions" : 1, - "pendingJobs" : 1, - "doneJobs" : 0, - "pregelConductors" : 0, - "lowPrioOngoingRequests" : 1, - "lowPrioQueuedRequests" : 0, - "allClear" : false -} -``` - -Once all numbers have gone to 0, the flag `allClear` is set and the -Coordinator shuts down automatically. This API is not available on -DB-Servers and Agents. +This API is not available on DB-Servers and Agents. @RESTRETURNCODES @RESTRETURNCODE{200} -Returned in all cases. +The response indicates the fact that a soft shutdown is ongoing and the +number of active operations of the various types. Once all numbers have gone +to 0, the flag `allClear` is set and the Coordinator shuts down automatically. @RESTREPLYBODY{softShutdownOngoing,boolean,required,} Whether a soft shutdown of the Coordinator is in progress. From da375025cf96d48eb1492ff3af7758cf80f56a30 Mon Sep 17 00:00:00 2001 From: Simran Date: Wed, 30 Jun 2021 19:09:25 +0200 Subject: [PATCH 7/8] Update delete_api_shutdown.md --- .../Rest/Administration/delete_api_shutdown.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md index ad44a4034635..16b9f378a80a 100644 --- a/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md @@ -7,19 +7,21 @@ @RESTQUERYPARAMETERS @RESTQUERYPARAM{soft,boolean,optional} +Introduced in: v3.7.12, v3.8.1, v3.9.0 + If set to `true`, this initiates a soft shutdown. This is only available -on coordinators. When issued, the coordinator tracks a number of ongoing +on Coordinators. When issued, the Coordinator tracks a number of ongoing operations, waits until all have finished, and then shuts itself down normally. In the meantime, new operations of these types are no longer accepted and a 503 response is sent instead. However, further requests to finish the ongoing operations are allowed. This feature can be used -to make restart operations of coordinators less intrusive for clients. +to make restart operations of Coordinators less intrusive for clients. The following types of operations are tracked: - AQL cursors (in particular streaming cursors) - - Transactions (in particular streaming transactions) - - Pregel runs (conducted by this coordinator) + - Transactions (in particular stream transactions) + - Pregel runs (conducted by this Coordinator) - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header - Finished asynchronous requests, whose result has not yet been collected @@ -29,9 +31,6 @@ The following types of operations are tracked: Note that the latter two are tracked but not prevented from being started, to allow for finishing operations. -This query parameter was introduced in 3.7.12, 3.8.1 and all versions -greater or equal than 3.9. - @RESTDESCRIPTION This call initiates a clean shutdown sequence. Requires administrive privileges. From 820ff5fd3156281260b36f7a00abc44690bdd492 Mon Sep 17 00:00:00 2001 From: Simran Date: Wed, 30 Jun 2021 19:10:42 +0200 Subject: [PATCH 8/8] Update get_api_shutdown.md --- .../DocuBlocks/Rest/Administration/get_api_shutdown.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md index 017394b399d2..213e4195fc75 100644 --- a/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md +++ b/Documentation/DocuBlocks/Rest/Administration/get_api_shutdown.md @@ -8,7 +8,7 @@ Introduced in: v3.7.12, v3.8.1, v3.9.0 This call reports progress about a soft Coordinator shutdown (see -documentation of `DELETE /_admin/shutdown?soft=true`). +documentation of `DELETE /_admin/shutdown?soft=true`). In this case, the following types of operations are tracked: - AQL cursors (in particular streaming cursors) @@ -20,7 +20,7 @@ In this case, the following types of operations are tracked: - Queued low priority requests (most normal requests) - Ongoing low priority requests -This API is not available on DB-Servers and Agents. +This API is only available on Coordinators. @RESTRETURNCODES