[DOCS] Reformats get rollup jobs API (#45114)
This commit is contained in:
Lisa Cawley
lcawl
parent
f5d1381e01
commit
bb22b2e45f
|
|
@ -1,46 +1,83 @@
|
|||
[role="xpack"]
|
||||
[testenv="basic"]
|
||||
[[rollup-get-job]]
|
||||
=== Get rollup jobs API
|
||||
=== Get {rollup-jobs} API
|
||||
++++
|
||||
<titleabbrev>Get job</titleabbrev>
|
||||
++++
|
||||
|
||||
Retrieves the configuration, stats, and status of {rollup-jobs}.
|
||||
|
||||
experimental[]
|
||||
|
||||
This API returns the configuration, stats and status of rollup jobs. The API can return the details for a single job,
|
||||
or for all jobs.
|
||||
|
||||
Note: This API only returns active (both `STARTED` and `STOPPED`) jobs. If a job was created, ran for a while then deleted,
|
||||
this API will not return any details about that job.
|
||||
|
||||
For details about a historical job, the <<rollup-get-rollup-caps,Rollup Capabilities API>> may be more useful
|
||||
|
||||
==== Request
|
||||
[[rollup-get-job-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET _rollup/job/<job_id>`
|
||||
|
||||
//===== Description
|
||||
[[rollup-get-job-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
==== Path Parameters
|
||||
* You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster
|
||||
privileges to use this API. For more information, see
|
||||
{stack-ov}/security-privileges.html[Security privileges].
|
||||
|
||||
`job_id`::
|
||||
(string) Identifier for the job to retrieve. If omitted (or `_all` is used) all jobs will be returned
|
||||
[[rollup-get-job-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The API can return the details for a single {rollup-job} or for all {rollup-jobs}.
|
||||
|
||||
==== Request Body
|
||||
NOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs. If a job
|
||||
was created, ran for a while then deleted, this API does not return any details
|
||||
about that job.
|
||||
|
||||
There is no request body for the Get Jobs API.
|
||||
For details about a historical {rollup-job}, the
|
||||
<<rollup-get-rollup-caps,rollup capabilities API>> may be more useful.
|
||||
|
||||
==== Authorization
|
||||
[[rollup-get-job-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
|
||||
For more information, see
|
||||
{xpack-ref}/security-privileges.html[Security Privileges].
|
||||
`<job_id>`::
|
||||
(Optional, string) Identifier for the {rollup-job}. If it is `_all` or omitted,
|
||||
the API returns all {rollup-jobs}.
|
||||
|
||||
==== Examples
|
||||
[[rollup-get-job-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
If we have already created a rollup job named `sensor`, the details about the job can be retrieved with:
|
||||
`jobs`::
|
||||
(array) An array of {rollup-job} resources.
|
||||
`config`:::
|
||||
(object) Contains the configuration for the {rollup-job}. This information
|
||||
is identical to the configuration that was supplied when creating the job
|
||||
via the <<rollup-put-job,create job API>>.
|
||||
`status`:::
|
||||
(object) Contains the current status of the indexer for the {rollup-job}.
|
||||
The possible values and their meanings are:
|
||||
+
|
||||
--
|
||||
- `stopped` means the indexer is paused and will not process data, even if its
|
||||
cron interval triggers.
|
||||
- `started` means the indexer is running, but not actively indexing data. When
|
||||
the cron interval triggers, the job's indexer will begin to process data.
|
||||
- `indexing` means the indexer is actively processing data and creating new
|
||||
rollup documents. When in this state, any subsequent cron interval triggers will
|
||||
be ignored because the job is already active with the prior trigger.
|
||||
- `abort` is a transient state, which is usually not witnessed by the user. It
|
||||
is used if the task needs to be shut down for some reason (job has been deleted,
|
||||
an unrecoverable error has been encountered, etc). Shortly after the `abort`
|
||||
state is set, the job will remove itself from the cluster.
|
||||
--
|
||||
`stats`:::
|
||||
(object) Contains transient statistics about the {rollup-job}, such as how
|
||||
many documents have been processed and how many rollup summary docs have
|
||||
been indexed. These stats are not persisted. If a node is restarted, these
|
||||
stats will be reset.
|
||||
|
||||
[[rollup-get-job-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
If we have already created a rollup job named `sensor`, the details about the
|
||||
job can be retrieved with:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -49,7 +86,7 @@ GET _rollup/job/sensor
|
|||
// CONSOLE
|
||||
// TEST[setup:sensor_rollup_job]
|
||||
|
||||
Which will yield the following response:
|
||||
The API yields the following response:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
|
|
@ -115,27 +152,7 @@ Which will yield the following response:
|
|||
----
|
||||
// TESTRESPONSE
|
||||
|
||||
The `jobs` array contains a single job (`id: sensor`) since we requested a single job in the endpoint's URL. The
|
||||
details for this job contain three top-level parameters: `config`, `status` and `stats`
|
||||
|
||||
`config` holds the rollup job's configuration, which is identical to the configuration that was supplied when creating
|
||||
the job via the <<rollup-put-job,Create Job API>>.
|
||||
|
||||
The `status` object holds the current status of the rollup job's indexer. The possible values and their meanings are:
|
||||
|
||||
- `stopped` means the indexer is paused and will not process data, even if it's cron interval triggers
|
||||
- `started` means the indexer is running, but not actively indexing data. When the cron interval triggers, the job's
|
||||
indexer will begin to process data
|
||||
- `indexing` means the indexer is actively processing data and creating new rollup documents. When in this state, any
|
||||
subsequent cron interval triggers will be ignored because the job is already active with the prior trigger
|
||||
- `abort` a transient state, which is usually not witnessed by the user. The `abort` state is used if the task needs to
|
||||
be shut down for some reason (job has been deleted, an unrecoverable error has been encountered, etc). Shortly after
|
||||
the `abort` state is set, the job will remove itself from the cluster
|
||||
|
||||
Finally, the `stats` object provides transient statistics about the rollup job, such as how many documents have been
|
||||
processed and how many rollup summary docs have been indexed. These stats are not persisted, so if a node is restarted
|
||||
these stats will be reset.
|
||||
|
||||
The `jobs` array contains a single job (`id: sensor`) since we requested a single job in the endpoint's URL.
|
||||
If we add another job, we can see how multi-job responses are handled:
|
||||
|
||||
[source,js]
|
||||
|
|
|
|||
Loading…
Reference in New Issue