315 lines
9.6 KiB
Plaintext
315 lines
9.6 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[ilm-explain-lifecycle]]
|
|
=== Explain lifecycle API
|
|
++++
|
|
<titleabbrev>Explain lifecycle</titleabbrev>
|
|
++++
|
|
|
|
Retrieves the current lifecycle status for one or more indices. For data
|
|
streams, the API retrieves the current lifecycle status for the stream's backing
|
|
indices.
|
|
|
|
[[ilm-explain-lifecycle-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET <target>/_ilm/explain`
|
|
|
|
[[ilm-explain-lifecycle-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`view_index_metadata` or `manage_ilm` or both privileges on the indices being
|
|
managed to use this API. For more information, see <<security-privileges>>.
|
|
|
|
[[ilm-explain-lifecycle-desc]]
|
|
==== {api-description-title}
|
|
|
|
Retrieves information about the index's current lifecycle state, such as
|
|
the currently executing phase, action, and step. Shows when the index entered
|
|
each one, the definition of the running phase, and information
|
|
about any failures.
|
|
|
|
[[ilm-explain-lifecycle-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Required, string)
|
|
Comma-separated list of data streams, indices, and index aliases to target.
|
|
Wildcard expressions (`*`) are supported.
|
|
+
|
|
To target all data streams and indices in a cluster, use `_all` or `*`.
|
|
|
|
[[ilm-explain-lifecycle-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`only_managed`::
|
|
(Optional, boolean) Filters the returned indices to only indices that are managed by
|
|
{ilm-init}.
|
|
|
|
`only_errors`::
|
|
(Optional, boolean) Filters the returned indices to only indices that are managed by
|
|
{ilm-init} and are in an error state, either due to an encountering an error while
|
|
executing the policy, or attempting to use a policy that does not exist.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
[[ilm-explain-lifecycle-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example retrieves the lifecycle state of `my_index`:
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _ilm/policy/my_policy
|
|
{
|
|
"policy": {
|
|
"phases": {
|
|
"warm": {
|
|
"min_age": "10d",
|
|
"actions": {
|
|
"forcemerge": {
|
|
"max_num_segments": 1
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"min_age": "30d",
|
|
"actions": {
|
|
"delete": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT my_index
|
|
{
|
|
"settings": {
|
|
"index.lifecycle.name": "my_policy",
|
|
"index.number_of_replicas": 0
|
|
}
|
|
}
|
|
|
|
GET /_cluster/health?wait_for_status=green&timeout=10s
|
|
--------------------------------------------------
|
|
// TEST
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET my_index/_ilm/explain
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
When management of the index is first taken over by {ilm-init}, `explain` shows
|
|
that the index is managed and in the `new` phase:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"my_index": {
|
|
"index": "my_index",
|
|
"managed": true, <1>
|
|
"policy": "my_policy", <2>
|
|
"lifecycle_date_millis": 1538475653281, <3>
|
|
"age": "15s", <4>
|
|
"phase": "new",
|
|
"phase_time_millis": 1538475653317, <5>
|
|
"action": "complete",
|
|
"action_time_millis": 1538475653317, <6>
|
|
"step": "complete",
|
|
"step_time_millis": 1538475653317 <7>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:no way to know if we will get this response immediately]
|
|
|
|
<1> Shows if the index is being managed by {ilm-init}. If the index is not managed by
|
|
{ilm-init} the other fields will not be shown
|
|
<2> The name of the policy which {ilm-init} is using for this index
|
|
<3> The timestamp used for the `min_age`
|
|
<4> The age of the index (used for calculating when to enter the next phase)
|
|
<5> When the index entered the current phase
|
|
<6> When the index entered the current action
|
|
<7> When the index entered the current step
|
|
|
|
Once the policy is running on the index, the response includes a
|
|
`phase_execution` object that shows the definition of the current phase.
|
|
Changes to the underlying policy will not affect this index until the current
|
|
phase completes.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000069": {
|
|
"index": "test-000069",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"age": "25.14s",
|
|
"phase": "hot",
|
|
"phase_time_millis": 1538475653317,
|
|
"phase_time": "2018-10-15T13:45:22.577Z",
|
|
"action": "rollover",
|
|
"action_time_millis": 1538475653317,
|
|
"action_time": "2018-10-15T13:45:22.577Z",
|
|
"step": "attempt-rollover",
|
|
"step_time_millis": 1538475653317,
|
|
"step_time": "2018-10-15T13:45:22.577Z",
|
|
"phase_execution": {
|
|
"policy": "my_lifecycle3",
|
|
"phase_definition": { <1>
|
|
"min_age": "0ms",
|
|
"actions": {
|
|
"rollover": {
|
|
"max_age": "30s"
|
|
}
|
|
}
|
|
},
|
|
"version": 3, <2>
|
|
"modified_date": "2018-10-15T13:21:41.576Z", <3>
|
|
"modified_date_in_millis": 1539609701576 <4>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
|
|
|
|
<1> The JSON phase definition loaded from the specified policy when the index
|
|
entered this phase
|
|
<2> The version of the policy that was loaded
|
|
<3> The date the loaded policy was last modified
|
|
<4> The epoch time when the loaded policy was last modified
|
|
|
|
If {ilm-init} is waiting for a step to complete, the response includes status
|
|
information for the step that's being performed on the index.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000020": {
|
|
"index": "test-000020",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"age": "4.12m",
|
|
"phase": "warm",
|
|
"phase_time_millis": 1538475653317,
|
|
"phase_time": "2018-10-15T13:45:22.577Z",
|
|
"action": "allocate",
|
|
"action_time_millis": 1538475653317,
|
|
"action_time": "2018-10-15T13:45:22.577Z",
|
|
"step": "check-allocation",
|
|
"step_time_millis": 1538475653317,
|
|
"step_time": "2018-10-15T13:45:22.577Z",
|
|
"step_info": { <1>
|
|
"message": "Waiting for all shard copies to be active",
|
|
"shards_left_to_allocate": -1,
|
|
"all_shards_active": false,
|
|
"actual_replicas": 2
|
|
},
|
|
"phase_execution": {
|
|
"policy": "my_lifecycle3",
|
|
"phase_definition": {
|
|
"min_age": "0ms",
|
|
"actions": {
|
|
"allocate": {
|
|
"number_of_replicas": 2,
|
|
"include": {
|
|
"box_type": "warm"
|
|
},
|
|
"exclude": {},
|
|
"require": {}
|
|
},
|
|
"forcemerge": {
|
|
"max_num_segments": 1
|
|
}
|
|
}
|
|
},
|
|
"version": 2,
|
|
"modified_date": "2018-10-15T13:20:02.489Z",
|
|
"modified_date_in_millis": 1539609602489
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
|
|
|
|
<1> Status of the step that's in progress.
|
|
|
|
If the index is in the ERROR step, something went wrong while executing a
|
|
step in the policy and you will need to take action for the index to proceed
|
|
to the next step. Some steps are safe to automatically be retried in certain
|
|
circumstances. To help you diagnose the problem, the explain response shows
|
|
the step that failed, the step info which provides information about the error,
|
|
and information about the retry attempts executed for the failed step if it's
|
|
the case.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000056": {
|
|
"index": "test-000056",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"age": "50.1d",
|
|
"phase": "hot",
|
|
"phase_time_millis": 1538475653317,
|
|
"phase_time": "2018-10-15T13:45:22.577Z",
|
|
"action": "rollover",
|
|
"action_time_millis": 1538475653317,
|
|
"action_time": "2018-10-15T13:45:22.577Z",
|
|
"step": "ERROR",
|
|
"step_time_millis": 1538475653317,
|
|
"step_time": "2018-10-15T13:45:22.577Z",
|
|
"failed_step": "check-rollover-ready", <1>
|
|
"is_auto_retryable_error": true, <2>
|
|
"failed_step_retry_count": 1, <3>
|
|
"step_info": { <4>
|
|
"type": "cluster_block_exception",
|
|
"reason": "index [test-000057/H7lF9n36Rzqa-KfKcnGQMg] blocked by: [FORBIDDEN/5/index read-only (api)",
|
|
"index_uuid": "H7lF9n36Rzqa-KfKcnGQMg",
|
|
"index": "test-000057"
|
|
},
|
|
"phase_execution": {
|
|
"policy": "my_lifecycle3",
|
|
"phase_definition": {
|
|
"min_age": "0ms",
|
|
"actions": {
|
|
"rollover": {
|
|
"max_age": "30s"
|
|
}
|
|
}
|
|
},
|
|
"version": 3,
|
|
"modified_date": "2018-10-15T13:21:41.576Z",
|
|
"modified_date_in_millis": 1539609701576
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
|
|
|
|
<1> The step that caused the error
|
|
<2> Indicates if retrying the failed step can overcome the error. If this
|
|
is true, {ilm-init} will retry the failed step automatically.
|
|
<3> Shows the number of attempted automatic retries to execute the failed
|
|
step.
|
|
<4> What went wrong
|