elasticsearch/docs/reference/dlm/apis/explain-data-lifecycle.asciidoc

[[dlm-explain-lifecycle]]
=== Explain Lifecycle API
++++
<titleabbrev>Explain Data Lifecycle</titleabbrev>
++++

experimental::[]

Retrieves the current data lifecycle status for one or more data stream backing indices.

[[dlm-explain-lifecycle-request]]
==== {api-request-title}

`GET <target>/_lifecycle/explain`

[[dlm-explain-lifecycle-desc]]
==== {api-description-title}

Retrieves information about the index's current DLM lifecycle state, such as
time since index creation, time since rollover, the lifecycle configuration
managing the index, or any error that {es} might've encountered during the lifecycle
execution.

[[dlm-explain-lifecycle-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string) Comma-separated list of indices.

[[dlm-explain-lifecycle-query-params]]
==== {api-query-parms-title}

`include_defaults`::
  (Optional, Boolean) Includes default configurations related to the lifecycle of the target index.
  Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[[dlm-explain-lifecycle-example]]
==== {api-examples-title}

The following example retrieves the lifecycle state of the index `.ds-metrics-2023.03.22-000001`:

[source,console]
--------------------------------------------------
GET .ds-metrics-2023.03.22-000001/_lifecycle/explain
--------------------------------------------------
// TEST[skip:we're not setting up DLM in these tests]

If the index is managed by DLM `explain` will show the `managed_by_dlm` field
set to `true` and the rest of the response will contain information about the
lifecycle execution status for this index:

[source,console-result]
--------------------------------------------------
{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_dlm" : true,                        <1>
      "index_creation_date_millis" : 1679475563571,   <2>
      "time_since_index_creation" : "843ms",          <3>
      "rollover_date_millis" : 1679475564293,         <4>
      "time_since_rollover" : "121ms",                <5>
      "lifecycle" : { },                              <6>
      "generation_time" : "121ms"                     <7>
  }
}
--------------------------------------------------
// TESTRESPONSE[skip:the result is for illustrating purposes only]

<1> Shows if the index is being managed by DLM. If the index is not managed by
DLM the other fields will not be shown
<2> When the index was created, this timestamp is used to determine when to
rollover
<3> The time since the index creation (used for calculating when to rollover
the index via the `max_age`)
<4> When the index was rolled over. If the index was not rolled over this will not be
shown.
<5> The time since rollover. If the index was not rolled over this will not be shown.
<6> The lifecycle configuration that applies to this index (which is configured on the parent
data stream)
<7> The generation time of the index represents the time since the index started progressing
towards the user configurable / business specific parts of the lifecycle (e.g. retention).
Every index will have to wait for it to be rolled over before being able to progress to the
business-specific part of the lifecycle (i.e. the index advances in its lifecycle after it
stops being the write index of a data stream). If the index has not been rolled over the
`generation_time` will not be reported.

The `explain` will also report any errors related to the lifecycle execution for the target
index:

[source,console-result]
--------------------------------------------------
{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_dlm" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "lifecycle" : { },
      "error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"        <1>
  }
}
--------------------------------------------------
// TESTRESPONSE[skip:the result is for illustrating purposes only]

<1> The target index could not be rolled over due to a limitation in the number of shards
allowed in the cluster.