IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Get index lifecycle management status API Start index lifecycle management API »

› › ›

Explain lifecycle API

edit

Explain lifecycle API

edit

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.

Request

edit

GET <target>/_ilm/explain

Prerequisites

edit

If the Elasticsearch 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.

Description

edit

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

edit

<target>: (Required, string) Comma-separated list of data streams, indices, and aliases to target. Supports wildcards (*).To target all data streams and indices, use * or _all.

Query parameters

edit

only_managed: (Optional, Boolean) Filters the returned indices to only indices that are managed by ILM.
only_errors: (Optional, Boolean) Filters the returned indices to only indices that are managed by ILM 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.
master_timeout: (Optional, time units) Period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. Defaults to 30s. Can also be set to -1 to indicate that the request should never timeout.

Examples

edit

The following example retrieves the lifecycle state of my-index-000001:

resp = client.ilm.explain_lifecycle(
    index="my-index-000001",
    human=True,
)
print(resp)

response = client.ilm.explain_lifecycle(
  index: 'my-index-000001',
  human: true
)
puts response

const response = await client.ilm.explainLifecycle({
  index: "my-index-000001",
  human: "true",
});
console.log(response);

GET my-index-000001/_ilm/explain?human

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-000001": {
      "index": "my-index-000001",
      "index_creation_date_millis": 1538475653281,        
      "index_creation_date": "2018-10-15T13:45:21.981Z",
      "time_since_index_creation": "15s",                 
      "managed": true,                                    
      "policy": "my_policy",                              
      "lifecycle_date_millis": 1538475653281,             
      "lifecycle_date": "2018-10-15T13:45:21.981Z",
      "age": "15s",                                       
      "phase": "new",
      "phase_time_millis": 1538475653317,                 
      "phase_time": "2018-10-15T13:45:22.577Z",
      "action": "complete"
      "action_time_millis": 1538475653317,                
      "action_time": "2018-10-15T13:45:22.577Z",
      "step": "complete",
      "step_time_millis": 1538475653317,                  
      "step_time": "2018-10-15T13:45:22.577Z"
    }
  }
}

	When the index was created, this timestamp is used to determine when to rollover
	The time since the index creation (used for calculating when to rollover the index via the `max_age`)
	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 `min_age`
	The age of the index (used for calculating when to enter the next phase)
	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",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "25.14s",
      "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": { 
          "min_age": "0ms",
          "actions": {
            "rollover": {
              "max_age": "30s",
              "max_primary_shard_docs": 200000000, 
              "min_docs": 1
            }
          }
        },
        "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 rollover action includes the default `max_primary_shard_docs` and `min_docs` conditions. See ILM Rollover Options for more information.
	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",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "4.12m",
      "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": { 
        "message": "Waiting for all shard copies to be active",
        "shards_left_to_allocate": -1,
        "all_shards_active": false,
        "number_of_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
      }
    }
  }
}

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.

{
  "indices": {
    "test-000056": {
      "index": "test-000056",
      "index_creation_date_millis": 1538475653281,
      "time_since_index_creation": "50.1d",
      "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", 
      "is_auto_retryable_error": true, 
      "failed_step_retry_count": 1, 
      "step_info": { 
        "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
      }
    }
  }
}

	The step that caused the error
	Indicates if retrying the failed step can overcome the error. If this is true, ILM will retry the failed step automatically.
	Shows the number of attempted automatic retries to execute the failed step.
	What went wrong

« Get index lifecycle management status API Start index lifecycle management API »