mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
223385f887
This adds an {index}/_lifecycle/explain API to retrieve information
about an index's status within its lifecycle.
The response looks like so:
```
"indices" : {
".ds-metrics-foo-2023.03.22-000001" : {
"index" : ".ds-metrics-foo-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"
},
".ds-metrics-foo-2023.03.22-000002" : {
"index" : ".ds-metrics-foo-2023.03.22-000002",
"managed_by_dlm" : true,
"index_creation_date_millis" : 1679475564351,
"time_since_index_creation" : "63ms",
"lifecycle" : { }
}
}
}
```
111 lines
4.2 KiB
Text
111 lines
4.2 KiB
Text
[[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.
|