Explain Lifecycle API

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

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

Request

edit

GET <target>/_lifecycle/explain

Description

edit

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 Elasticsearch might’ve encountered during the lifecycle execution.

Path parameters

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

Query parameters

edit
include_defaults
(Optional, Boolean) Includes default configurations related to the lifecycle of the target index. Defaults to false.
master_timeout
(Optional, time units) Period 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.
timeout
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Examples

edit

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

GET .ds-metrics-2023.03.22-000001/_lifecycle/explain

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:

{
  "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",          
      "rollover_date_millis" : 1679475564293,         
      "time_since_rollover" : "121ms",                
      "lifecycle" : { },                              
      "generation_time" : "121ms"                     
  }
}

Shows if the index is being managed by DLM. If the index is not managed by DLM the other fields will not be shown

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)

When the index was rolled over. If the index was not rolled over this will not be shown.

The time since rollover. If the index was not rolled over this will not be shown.

The lifecycle configuration that applies to this index (which is configured on the parent data stream)

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). The generation_time is calculated from the origination date if it exists, or from the rollover date if it exists, or from the creation date if neither of the other two exist. If the index is the write index the generation_time will not be reported because it is not eligible for retention or other parts of the lifecycle.

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

{
  "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;\"}"        
  }
}

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