282 lines
8.0 KiB
Plaintext
282 lines
8.0 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[ilm-explain-lifecycle]]
|
|
=== Explain lifecycle API
|
|
++++
|
|
<titleabbrev>Explain lifecycle</titleabbrev>
|
|
++++
|
|
|
|
Shows an index's current lifecycle status.
|
|
|
|
==== Request
|
|
|
|
`GET <index>/_ilm/explain`
|
|
|
|
==== Description
|
|
|
|
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.
|
|
|
|
==== Path Parameters
|
|
|
|
`index` (required)::
|
|
(string) Identifier for the index.
|
|
|
|
==== Request Parameters
|
|
|
|
include::{docdir}/rest-api/timeoutparms.asciidoc[]
|
|
|
|
==== Authorization
|
|
|
|
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 {stack-ov}/security-privileges.html[Security Privileges].
|
|
|
|
==== Examples
|
|
|
|
The following example retrieves the lifecycle state of `my_index`:
|
|
|
|
//////////////////////////
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
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
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
//////////////////////////
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET my_index/_ilm/explain
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
When management of the index is first taken over by ILM, `explain` shows
|
|
that the index is managed and in the `new` phase:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"my_index": {
|
|
"index": "my_index",
|
|
"managed": true, <1>
|
|
"policy": "my_policy", <2>
|
|
"lifecycle_date_millis": 1538475653281, <3>
|
|
"phase": "new",
|
|
"phase_time_millis": 1538475653317, <4>
|
|
"action": "complete",
|
|
"action_time_millis": 1538475653317, <5>
|
|
"step": "complete",
|
|
"step_time_millis": 1538475653317 <6>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TESTRESPONSE[skip:no way to know if we will get this response immediately]
|
|
<1> Shows if the index is being managed by ILM. If the index is not managed by
|
|
ILM the other fields will not be shown
|
|
<2> The name of the policy which ILM is using for this index
|
|
<3> The timestamp used for the `min_age`
|
|
<4> When the index entered the current phase
|
|
<5> When the index entered the current action
|
|
<6> 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,js]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000069": {
|
|
"index": "test-000069",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"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>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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,js]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000020": {
|
|
"index": "test-000020",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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 and you will need to take action for the index to proceed
|
|
to the next step. To help you diagnose the problem, the explain response shows
|
|
the step that failed and the step info provides information about the error.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
"test-000056": {
|
|
"index": "test-000056",
|
|
"managed": true,
|
|
"policy": "my_lifecycle3",
|
|
"lifecycle_date_millis": 1538475653281,
|
|
"lifecycle_date": "2018-10-15T13:45:21.981Z",
|
|
"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": "attempt-rollover", <1>
|
|
"step_info": { <2>
|
|
"type": "resource_already_exists_exception",
|
|
"reason": "index [test-000057/H7lF9n36Rzqa-KfKcnGQMg] already exists",
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
|
|
<1> The step that caused the error
|
|
<2> What went wrong
|