OpenSearch/docs/reference/ilm/apis/explain.asciidoc

[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-000001`:

//////////////////////////

[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-000001
{
  "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-000001/_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-000001": {
      "index": "my-index-000001",
      "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