Explain lifecycle API
editExplain lifecycle API
editShows an index’s current lifecycle status.
Request
editGET <index>/_ilm/explain
Description
editRetrieves 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
edit-
index
(required) - (string) Identifier for the index.
Request Parameters
edit-
timeout
-
(time units) Specifies the period of time to wait for a response. If no
response is received before the timeout expires, the request fails and
returns an error. Defaults to
30s
. For more information about time units, see Time units. -
master_timeout
-
(time units) Specifies the period of time to wait for a connection to the
master node. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to
30s
. For more information about time units, see Time units.
Authorization
editYou 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.
Examples
editThe following example retrieves the lifecycle state of my_index
:
GET my_index/_ilm/explain
When management of the index is first taken over by ILM, explain
shows
that the index is managed and in the new
phase:
{ "indices": { "my_index": { "index": "my_index", "managed": true, "policy": "my_policy", "lifecycle_date_millis": 1538475653281, "phase": "new", "phase_time_millis": 1538475653317, "action": "complete", "action_time_millis": 1538475653317, "step": "complete", "step_time_millis": 1538475653317 } } }
Shows if the index is being managed by ILM. If the index is not managed by ILM the other fields will not be shown |
|
The name of the policy which ILM is using for this index |
|
The timestamp used for the |
|
When the index entered the current phase |
|
When the index entered the current action |
|
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.
{ "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": { "min_age": "0ms", "actions": { "rollover": { "max_age": "30s" } } }, "version": 3, "modified_date": "2018-10-15T13:21:41.576Z", "modified_date_in_millis": 1539609701576 } } } }
The JSON phase definition loaded from the specified policy when the index entered this phase |
|
The version of the policy that was loaded |
|
The date the loaded policy was last modified |
|
The epoch time when the loaded policy was last modified |
If ILM is waiting for a step to complete, the response includes status information for the step that’s being performed on the index.
{ "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": { "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 } } } }
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. To help you diagnose the problem, the explain response shows the step that failed and the step info provides information about the error.
{ "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", "step_info": { "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 } } } }