[DOCS] Reformat rollup APIs to use new API format (#44131)

This commit is contained in:
Lisa Cawley 2019-07-10 15:12:32 -07:00 committed by lcawl
parent fa36f82277
commit 00b16e332d
6 changed files with 188 additions and 250 deletions

View File

@ -17,12 +17,12 @@ Most rollup endpoints have the following base:
[[rollup-api-jobs]]
=== /job/
* {ref}/rollup-put-job.html[PUT /_rollup/job/<job_id+++>+++]: Create a job
* {ref}/rollup-get-job.html[GET /_rollup/job]: List jobs
* {ref}/rollup-get-job.html[GET /_rollup/job/<job_id+++>+++]: Get job details
* {ref}/rollup-start-job.html[POST /_rollup/job/<job_id>/_start]: Start a job
* {ref}/rollup-stop-job.html[POST /_rollup/job/<job_id>/_stop]: Stop a job
* {ref}/rollup-delete-job.html[DELETE /_rollup/job/<job_id+++>+++]: Delete a job
* {ref}/rollup-put-job.html[PUT /_rollup/job/<job_id+++>+++]: Create a {rollup-job}
* {ref}/rollup-get-job.html[GET /_rollup/job]: List {rollup-jobs}
* {ref}/rollup-get-job.html[GET /_rollup/job/<job_id+++>+++]: Get {rollup-job} details
* {ref}/rollup-start-job.html[POST /_rollup/job/<job_id>/_start]: Start a {rollup-job}
* {ref}/rollup-stop-job.html[POST /_rollup/job/<job_id>/_stop]: Stop a {rollup-job}
* {ref}/rollup-delete-job.html[DELETE /_rollup/job/<job_id+++>+++]: Delete a {rollup-job}
[float]
[[rollup-api-data]]

View File

@ -1,27 +1,48 @@
[role="xpack"]
[testenv="basic"]
[[rollup-delete-job]]
=== Delete job API
=== Delete {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Delete job</titleabbrev>
<titleabbrev>Delete {rollup-jobs}</titleabbrev>
++++
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/<job_id>`
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/<job_id>`
`<job_id>`::
(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/]

View File

@ -1,61 +1,74 @@
[role="xpack"]
[testenv="basic"]
[[rollup-put-job]]
=== Create job API
=== Create {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Create job</titleabbrev>
<titleabbrev>Create {rollup-jobs}</titleabbrev>
++++
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 <<rollup-start-job,Start Job API>>.
==== Request
[[sample-api-request]]
==== {api-request-title}
`PUT _rollup/job/<job_id>`
//===== 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
<<rollup-start-job,start {rollup-jobs} API>>.
==== 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 <<rollup-job-config,{rollup-job} config>>.
`groups` (required)::
(object) Defines the grouping fields that are defined for this rollup job. See <<rollup-job-config,rollup job config>>.
`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 <<rollup-job-config,rollup job config>>.
(object) Optional. Defines the metrics to collect for each grouping tuple. See
<<rollup-job-config,{rollup-job} config>>.
`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 <<rollup-job-config>>.
==== 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]
--------------------------------------------------

View File

@ -1,41 +1,51 @@
[role="xpack"]
[testenv="basic"]
[[rollup-start-job]]
=== Start rollup job API
=== Start {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Start job</titleabbrev>
<titleabbrev>Start {rollup-jobs}</titleabbrev>
++++
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/<job_id>/_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}
`<job_id>`::
(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]
--------------------------------------------------
@ -53,34 +63,3 @@ Which will return the response:
}
----
// 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/]

View File

@ -1,108 +1,75 @@
[role="xpack"]
[testenv="basic"]
[[rollup-stop-job]]
=== Stop rollup job API
=== Stop {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Stop job</titleabbrev>
<titleabbrev>Stop {rollup-jobs}</titleabbrev>
++++
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/<job_id>/_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/]
`<job_id>`::
(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:
--
[source,js]
--------------------------------------------------
POST _rollup/job/does_not_exist/_stop
--------------------------------------------------
// CONSOLE
// TEST[catch:missing]
`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`.
A 404 `resource_not_found` exception will be thrown:
[[rollup-stop-job-response-codes]]
==== {api-response-codes-title}
[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/]
`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.
===== Waiting for the job to stop
[[rollup-stop-job-examples]]
==== {api-examples-title}
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.
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.

View File

@ -7,9 +7,9 @@
[[rollup-jobs-endpoint]]
=== Jobs
* <<rollup-put-job,Create Job>>, <<rollup-delete-job,Delete Job>>,
* <<rollup-start-job,Start Job>>, <<rollup-stop-job,Stop Job>>,
* <<rollup-get-job,Get Job+++,+++ List all Jobs>>
* <<rollup-put-job,Create>> or <<rollup-delete-job,delete {rollup-jobs}>>
* <<rollup-start-job,Start>> or <<rollup-stop-job,stop {rollup-jobs}>>
* <<rollup-get-job,Get {rollup-jobs}>>
* <<rollup-job-config,Job configuration details>>
[float]
@ -26,13 +26,12 @@
* <<rollup-search,Rollup Search>>
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[]