Get the status for a data stream lifecycle Generally available; Added in 8.11.0

GET /{index}/_lifecycle/explain

Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

External documentation

Path parameters

index string | array[string] Required

The name of the index to explain

Query parameters

include_defaults boolean

indicates if the API should return the default values the system uses for the index's lifecycle
master_timeout string

Specify timeout for connection to master

External documentation

Responses

200 application/json
Hide response attribute Show response attribute object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  index string Required
  
  managed_by_lifecycle boolean Required
  
  index_creation_date_millis number
  
  Time unit for milliseconds
  
  time_since_index_creation string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  External documentation
  
  rollover_date_millis number
  
  Time unit for milliseconds
  
  time_since_rollover string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  External documentation
  
  lifecycle object
  
  Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.
  
  Hide lifecycle attribute Show lifecycle attribute object
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.
  
  generation_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  External documentation
  
  error string

GET /{index}/_lifecycle/explain

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

resp = client.indices.explain_data_lifecycle(
    index=".ds-metrics-2023.03.22-000001",
)

const response = await client.indices.explainDataLifecycle({
  index: ".ds-metrics-2023.03.22-000001",
});

response = client.indices.explain_data_lifecycle(
  index: ".ds-metrics-2023.03.22-000001"
)

$resp = $client->indices()->explainDataLifecycle([
    "index" => ".ds-metrics-2023.03.22-000001",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain"

Response examples (200)

A successful response from `GET .ds-metrics-2023.03.22-000001/_lifecycle/explain`, which retrieves the lifecycle status for a data stream backing index. If the index is managed by a data stream lifecycle, the API will show the `managed_by_lifecycle` 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_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "rollover_date_millis" : 1679475564293,
      "time_since_rollover" : "121ms",
      "lifecycle" : { },
      "generation_time" : "121ms"
  }
}

The API reports 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_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "lifecycle" : {
        "enabled": true
      },
      "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;\"}"
  }
}