From 00b16e332dd9d64785be007eef253453b5347897 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 10 Jul 2019 15:12:32 -0700 Subject: [PATCH] [DOCS] Reformat rollup APIs to use new API format (#44131) --- docs/reference/rollup/api-quickref.asciidoc | 12 +- .../reference/rollup/apis/delete-job.asciidoc | 111 ++++++-------- docs/reference/rollup/apis/put-job.asciidoc | 77 +++++----- docs/reference/rollup/apis/start-job.asciidoc | 89 +++++------- docs/reference/rollup/apis/stop-job.asciidoc | 136 +++++++----------- docs/reference/rollup/rollup-api.asciidoc | 13 +- 6 files changed, 188 insertions(+), 250 deletions(-) diff --git a/docs/reference/rollup/api-quickref.asciidoc b/docs/reference/rollup/api-quickref.asciidoc index d1ea03b6284..d6be3e4e5b6 100644 --- a/docs/reference/rollup/api-quickref.asciidoc +++ b/docs/reference/rollup/api-quickref.asciidoc @@ -17,12 +17,12 @@ Most rollup endpoints have the following base: [[rollup-api-jobs]] === /job/ -* {ref}/rollup-put-job.html[PUT /_rollup/job/+++]: Create a job -* {ref}/rollup-get-job.html[GET /_rollup/job]: List jobs -* {ref}/rollup-get-job.html[GET /_rollup/job/+++]: Get job details -* {ref}/rollup-start-job.html[POST /_rollup/job//_start]: Start a job -* {ref}/rollup-stop-job.html[POST /_rollup/job//_stop]: Stop a job -* {ref}/rollup-delete-job.html[DELETE /_rollup/job/+++]: Delete a job +* {ref}/rollup-put-job.html[PUT /_rollup/job/+++]: Create a {rollup-job} +* {ref}/rollup-get-job.html[GET /_rollup/job]: List {rollup-jobs} +* {ref}/rollup-get-job.html[GET /_rollup/job/+++]: Get {rollup-job} details +* {ref}/rollup-start-job.html[POST /_rollup/job//_start]: Start a {rollup-job} +* {ref}/rollup-stop-job.html[POST /_rollup/job//_stop]: Stop a {rollup-job} +* {ref}/rollup-delete-job.html[DELETE /_rollup/job/+++]: Delete a {rollup-job} [float] [[rollup-api-data]] diff --git a/docs/reference/rollup/apis/delete-job.asciidoc b/docs/reference/rollup/apis/delete-job.asciidoc index 18c353ac736..74459316098 100644 --- a/docs/reference/rollup/apis/delete-job.asciidoc +++ b/docs/reference/rollup/apis/delete-job.asciidoc @@ -1,27 +1,48 @@ [role="xpack"] [testenv="basic"] [[rollup-delete-job]] -=== Delete job API +=== Delete {rollup-jobs} API +[subs="attributes"] ++++ -Delete job +Delete {rollup-jobs} ++++ +Deletes an existing {rollup-job}. + experimental[] -This API deletes an existing rollup job. A job must be *stopped* first before it can be deleted. Attempting to delete -a started job will result in an error. Similarly, attempting to delete a nonexistent job will throw an exception. +[[rollup-delete-job-request]] +==== {api-request-title} -.Deleting the job does not delete rolled up data -********************************** -When a job is deleted, that only removes the process that is actively monitoring and rolling up data. -It does not delete any previously rolled up data. This is by design; a user may wish to roll up a static dataset. Because -the dataset is static, once it has been fully rolled up there is no need to keep the indexing Rollup job around (as there -will be no new data). So the job may be deleted, leaving behind the rolled up data for analysis. +`DELETE _rollup/job/` -If you wish to also remove the rollup data, and the rollup index only contains the data for a single job, you can simply -delete the whole rollup index. If the rollup index stores data from several jobs, you must issue a Delete-By-Query that -targets the Rollup job's ID in the rollup index: +[[rollup-delete-job-prereqs]] +==== {api-prereq-title} +* If the {es} {security-features} are enabled, you must have `manage` or +`manage_rollup` cluster privileges to use this API. For more information, see +{stack-ov}/security-privileges.html[Security privileges]. + +[[rollup-delete-job-desc]] +==== {api-description-title} + +A job must be *stopped* first before it can be deleted. If you attempt to delete +a started job, an error occurs. Similarly, if you attempt to delete a +nonexistent job, an exception occurs. + +[IMPORTANT] +=============================== +When a job is deleted, that only removes the process that is actively monitoring +and rolling up data. It does not delete any previously rolled up data. This is +by design; a user may wish to roll up a static dataset. Because the dataset is +static, once it has been fully rolled up there is no need to keep the indexing +rollup job around (as there will be no new data). So the job can be deleted, +leaving behind the rolled up data for analysis. + +If you wish to also remove the rollup data, and the rollup index only contains +the data for a single job, you can simply delete the whole rollup index. If the +rollup index stores data from several jobs, you must issue a delete-by-query +that targets the rollup job's ID in the rollup index. [source,js] -------------------------------------------------- @@ -35,32 +56,23 @@ POST my_rollup_index/_delete_by_query } -------------------------------------------------- // NOTCONSOLE +=============================== -********************************** -==== Request +[[rollup-delete-job-path-params]] +==== {api-path-parms-title} -`DELETE _rollup/job/` +``:: + (string) Required. Identifier for the job. -//===== Description +[[rollup-delete-job-response-codes]] +==== {api-response-codes-title} -==== Path Parameters +`404` (Missing resources):: + This code indicates that there are no resources that match the request. It + occurs if you try to delete a job that doesn't exist. -`job_id` (required):: - (string) Identifier for the job - - -==== Request Body - -There is no request body for the Delete Job API. - -==== Authorization - -You must have `manage` or `manage_rollup` cluster privileges to use this API. -For more information, see -{xpack-ref}/security-privileges.html[Security Privileges]. - - -==== Examples +[[rollup-delete-job-example]] +==== {api-example-title} If we have a rollup job named `sensor`, it can be deleted with: @@ -80,34 +92,3 @@ Which will return the response: } ---- // TESTRESPONSE - -If however we try to delete a job which doesn't exist: - -[source,js] --------------------------------------------------- -DELETE _rollup/job/does_not_exist --------------------------------------------------- -// CONSOLE -// TEST[catch:missing] - -A 404 `resource_not_found` exception will be thrown: - -[source,js] ----- -{ - "error" : { - "root_cause" : [ - { - "type" : "resource_not_found_exception", - "reason" : "the task with id [does_not_exist] doesn't exist", - "stack_trace": ... - } - ], - "type" : "resource_not_found_exception", - "reason" : "the task with id [does_not_exist] doesn't exist", - "stack_trace": ... - }, - "status": 404 -} ----- -// TESTRESPONSE[s/"stack_trace": .../"stack_trace": $body.$_path/] diff --git a/docs/reference/rollup/apis/put-job.asciidoc b/docs/reference/rollup/apis/put-job.asciidoc index eac71a48b43..a0487494f6d 100644 --- a/docs/reference/rollup/apis/put-job.asciidoc +++ b/docs/reference/rollup/apis/put-job.asciidoc @@ -1,61 +1,74 @@ [role="xpack"] [testenv="basic"] [[rollup-put-job]] -=== Create job API +=== Create {rollup-jobs} API +[subs="attributes"] ++++ -Create job +Create {rollup-jobs} ++++ +Creates a {rollup-job}. + experimental[] -This API enables you to create a rollup job. The job will be created in a `STOPPED` state, and must be -started with the <>. - -==== Request +[[sample-api-request]] +==== {api-request-title} `PUT _rollup/job/` -//===== Description +[[sample-api-prereqs]] +==== {api-prereq-title} -==== Path Parameters +* If the {es} {security-features} are enabled, you must have `manage` or +`manage_rollup` cluster privileges to use this API. For more information, see +{stack-ov}/security-privileges.html[Security privileges]. -`job_id` (required):: - (string) Identifier for the job +[[sample-api-desc]] +==== {api-description-title} +Jobs are created in a `STOPPED` state. You can start them with the +<>. -==== Request Body +[[sample-api-path-params]] +==== {api-path-parms-title} -`index_pattern` (required):: - (string) The index, or index pattern, that you wish to rollup. Supports wildcard-style patterns (`logstash-*`). +`job_id`:: + (string) Required. Identifier for the {rollup-job}. -`rollup_index` (required):: - (string) The index that you wish to store rollup results into. Can be shared with other rollup jobs. +[[sample-api-request-body]] +==== {api-request-body-title} -`cron` (required):: - (string) A cron string which defines when the rollup job should be executed. +`cron`:: + (string) Required. A cron string which defines when the {rollup-job} should be executed. -`page_size` (required):: - (int) The number of bucket results that should be processed on each iteration of the rollup indexer. A larger value - will tend to execute faster, but will require more memory during processing. +`groups`:: + (object) Required. Defines the grouping fields that are defined for this + {rollup-job}. See <>. -`groups` (required):: - (object) Defines the grouping fields that are defined for this rollup job. See <>. +`index_pattern`:: + (string) Required. The index or index pattern to roll up. Supports + wildcard-style patterns (`logstash-*`). `metrics`:: - (object) Defines the metrics that should be collected for each grouping tuple. See <>. + (object) Optional. Defines the metrics to collect for each grouping tuple. See + <>. + +`page_size`:: + (integer) Required. The number of bucket results that are processed on each + iteration of the rollup indexer. A larger value tends to execute faster, but + requires more memory during processing. + +`rollup_index`:: + (string) Required. The index that contains the rollup results. The index can + be shared with other {rollup-jobs}. For more details about the job configuration, see <>. -==== Authorization +[[sample-api-example]] +==== {api-example-title} -You must have `manage` or `manage_rollup` cluster privileges to use this API. -For more information, see -{xpack-ref}/security-privileges.html[Security Privileges]. - - -==== Examples - -The following example creates a rollup job named "sensor", targeting the "sensor-*" index pattern: +The following example creates a {rollup-job} named "sensor", targeting the +"sensor-*" index pattern: [source,js] -------------------------------------------------- diff --git a/docs/reference/rollup/apis/start-job.asciidoc b/docs/reference/rollup/apis/start-job.asciidoc index 241d070a670..2a49383cdbb 100644 --- a/docs/reference/rollup/apis/start-job.asciidoc +++ b/docs/reference/rollup/apis/start-job.asciidoc @@ -1,41 +1,51 @@ [role="xpack"] [testenv="basic"] [[rollup-start-job]] -=== Start rollup job API +=== Start {rollup-jobs} API +[subs="attributes"] ++++ -Start job +Start {rollup-jobs} ++++ +Starts an existing, stopped {rollup-job}. + experimental[] -This API starts an existing, stopped rollup job. If the job does not exist an exception will be thrown. -Starting an already started job has no action. - -==== Request +[[rollup-start-job-request]] +==== {api-request-title} `POST _rollup/job//_start` -//===== Description +[[rollup-start-job-prereqs]] +==== {api-prereq-title} -==== Path Parameters - -`job_id` (required):: - (string) Identifier for the job - - -==== Request Body - -There is no request body for the Start Job API. - -==== Authorization - -You must have `manage` or `manage_rollup` cluster privileges to use this API. +* You must have `manage` or `manage_rollup` cluster privileges to use this API. For more information, see -{xpack-ref}/security-privileges.html[Security Privileges]. +{stack-ov}/security-privileges.html[Security privileges]. -==== Examples +[[rollup-start-job-desc]] +==== {api-description-title} -If we have already created a rollup job named `sensor`, it can be started with: +If you try to start a job that does not exist, an exception occurs. If you try +to start a job that is already started, nothing happens. + +[[rollup-start-job-path-params]] +==== {api-path-parms-title} + +``:: + (string) Required. Identifier for the {rollup-job}. + +[[rollup-start-job-response-codes]] +==== {api-response-codes-title} + + `404` (Missing resources):: + This code indicates that there are no resources that match the request. It + occurs if you try to start a job that doesn't exist. + +[[rollup-start-job-examples]] +==== {api-examples-title} + +If we have already created a {rollup-job} named `sensor`, it can be started with: [source,js] -------------------------------------------------- @@ -52,35 +62,4 @@ Which will return the response: "started": true } ---- -// TESTRESPONSE - -If however we try to start a job which doesn't exist: - -[source,js] --------------------------------------------------- -POST _rollup/job/does_not_exist/_start --------------------------------------------------- -// CONSOLE -// TEST[catch:missing] - -A 404 `resource_not_found` exception will be thrown: - -[source,js] ----- -{ - "error" : { - "root_cause" : [ - { - "type" : "resource_not_found_exception", - "reason" : "Task for Rollup Job [does_not_exist] not found", - "stack_trace": ... - } - ], - "type" : "resource_not_found_exception", - "reason" : "Task for Rollup Job [does_not_exist] not found", - "stack_trace": ... - }, - "status": 404 -} ----- -// TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/] +// TESTRESPONSE \ No newline at end of file diff --git a/docs/reference/rollup/apis/stop-job.asciidoc b/docs/reference/rollup/apis/stop-job.asciidoc index 35162246a5f..0e5ea1cf518 100644 --- a/docs/reference/rollup/apis/stop-job.asciidoc +++ b/docs/reference/rollup/apis/stop-job.asciidoc @@ -1,108 +1,75 @@ [role="xpack"] [testenv="basic"] [[rollup-stop-job]] -=== Stop rollup job API +=== Stop {rollup-jobs} API +[subs="attributes"] ++++ -Stop job +Stop {rollup-jobs} ++++ +Stops an existing, started {rollup-job}. + experimental[] -This API stops an existing, started rollup job. If the job does not exist an exception will be thrown. -Stopping an already stopped job has no action. - -==== Request +[[rollup-stop-job-request]] +==== {api-request-title} `POST _rollup/job//_stop` -//===== Description +[[rollup-stop-job-prereqs]] +==== {api-prereq-title} -==== Path Parameters - -`job_id` (required):: - (string) Identifier for the job - -==== Query Parameters - -`wait_for_completion` (optional):: - (boolean) if set to true, causes the API to block until the indexer state completely stops. If set to false, the - API returns immediately and the indexer will be stopped asynchronously in the background. Defaults to `false`. - -`timeout` (optional):: - (TimeValue) if `wait_for_completion=true`, the API will block for (at maximum) - the specified duration while waiting for the job to stop. If more than `timeout` time has passed, the API - will throw a timeout exception. Note: even if a timeout exception is thrown, the stop request is still processing and - will eventually move the job to `STOPPED`. The timeout simply means the API call itself timed out while waiting - for the status change. Defaults to `30s` - -==== Request Body - -There is no request body for the Stop Job API. - -==== Authorization - -You must have `manage` or `manage_rollup` cluster privileges to use this API. +* You must have `manage` or `manage_rollup` cluster privileges to use this API. For more information, see -{xpack-ref}/security-privileges.html[Security Privileges]. +{stack-ov}/security-privileges.html[Security privileges]. +[[rollup-stop-job-desc]] +===== {api-description-title} -==== Examples +If you try to stop a job that does not exist, an exception occurs. If you try +to stop a job that is already stopped, nothing happens. -If we have an already-started rollup job named `sensor`, it can be stopped with: +[[rollup-stop-job-path-parms]] +==== {api-path-parms-title} -[source,js] --------------------------------------------------- -POST _rollup/job/sensor/_stop --------------------------------------------------- -// CONSOLE -// TEST[setup:sensor_started_rollup_job] -// TEST[s/_stop/_stop?wait_for_completion=true&timeout=10s/] +``:: + (string) Required. Identifier for the {rollup-job}. -Which will return the response: +[[rollup-stop-job-query-parms]] +==== {api-query-parms-title} -[source,js] ----- -{ - "stopped": true -} ----- -// TESTRESPONSE +`timeout`:: + (TimeValue) Optional. If `wait_for_completion` is `true`, the API blocks for + (at maximum) the specified duration while waiting for the job to stop. If more + than `timeout` time has passed, the API throws a timeout exception. Defaults + to `30s`. ++ +-- +NOTE: Even if a timeout exception is thrown, the stop request is still +processing and eventually moves the job to `STOPPED`. The timeout simply means +the API call itself timed out while waiting for the status change. -If however we try to stop a job which doesn't exist: +-- + +`wait_for_completion`:: + (boolean) Optional. If set to `true`, causes the API to block until the + indexer state completely stops. If set to `false`, the API returns immediately + and the indexer is stopped asynchronously in the background. Defaults to + `false`. -[source,js] --------------------------------------------------- -POST _rollup/job/does_not_exist/_stop --------------------------------------------------- -// CONSOLE -// TEST[catch:missing] +[[rollup-stop-job-response-codes]] +==== {api-response-codes-title} -A 404 `resource_not_found` exception will be thrown: +`404` (Missing resources):: + This code indicates that there are no resources that match the request. It + occurs if you try to stop a job that doesn't exist. -[source,js] ----- -{ - "error" : { - "root_cause" : [ - { - "type" : "resource_not_found_exception", - "reason" : "Task for Rollup Job [does_not_exist] not found", - "stack_trace": ... - } - ], - "type" : "resource_not_found_exception", - "reason" : "Task for Rollup Job [does_not_exist] not found", - "stack_trace": ... - }, - "status": 404 -} ----- -// TESTRESPONSE[s/"stack_trace": .../"stack_trace": $body.$_path/] +[[rollup-stop-job-examples]] +==== {api-examples-title} -===== Waiting for the job to stop - -Since only a stopped job can be deleted, it can be useful to block the StopJob API until the indexer has fully -stopped. This is accomplished with the `wait_for_completion` query parameter, and optionally a `timeout`: +Since only a stopped job can be deleted, it can be useful to block the API until +the indexer has fully stopped. This is accomplished with the +`wait_for_completion` query parameter, and optionally a `timeout`: [source,js] @@ -112,7 +79,6 @@ POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s // CONSOLE // TEST[setup:sensor_started_rollup_job] -The parameter will block the API call from returning until either the job has moved to `STOPPED`, or the specified -time has elapsed. If the specified time elapses without the job moving to `STOPPED`, a timeout exception will be thrown. - -If `wait_for_completion=true` is specified without a `timeout`, a default timeout of 30 seconds is used. \ No newline at end of file +The parameter blocks the API call from returning until either the job has moved +to `STOPPED` or the specified time has elapsed. If the specified time elapses +without the job moving to `STOPPED`, a timeout exception is thrown. diff --git a/docs/reference/rollup/rollup-api.asciidoc b/docs/reference/rollup/rollup-api.asciidoc index 5981336d0a0..c156265c2ff 100644 --- a/docs/reference/rollup/rollup-api.asciidoc +++ b/docs/reference/rollup/rollup-api.asciidoc @@ -7,9 +7,9 @@ [[rollup-jobs-endpoint]] === Jobs -* <>, <>, -* <>, <>, -* <> +* <> or <> +* <> or <> +* <> * <> [float] @@ -26,13 +26,12 @@ * <> - +include::apis/put-job.asciidoc[] include::apis/delete-job.asciidoc[] include::apis/get-job.asciidoc[] -include::apis/put-job.asciidoc[] -include::apis/start-job.asciidoc[] -include::apis/stop-job.asciidoc[] include::apis/rollup-caps.asciidoc[] include::apis/rollup-index-caps.asciidoc[] include::apis/rollup-search.asciidoc[] include::apis/rollup-job-config.asciidoc[] +include::apis/start-job.asciidoc[] +include::apis/stop-job.asciidoc[] \ No newline at end of file