mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
124 lines
5 KiB
Text
124 lines
5 KiB
Text
[[data-streams-explain-lifecycle]]
|
|
=== Explain data stream lifecycle
|
|
++++
|
|
<titleabbrev>Explain Data Stream Lifecycle</titleabbrev>
|
|
++++
|
|
|
|
.New API reference
|
|
[sidebar]
|
|
--
|
|
For the most up-to-date API details, refer to {api-es}/group/endpoint-data-stream[Data stream APIs].
|
|
--
|
|
|
|
Retrieves the current <<data-stream-lifecycle,data stream lifecycle>> status for one or more data stream backing indices.
|
|
|
|
[[explain-lifecycle-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
If the {es} {security-features} are enabled, you must have at least the `manage_data_stream_lifecycle` index privilege or
|
|
`view_index_metadata` index privilege to use this API. For more information, see <<security-privileges>>.
|
|
|
|
[[data-streams-explain-lifecycle-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET <target>/_lifecycle/explain`
|
|
|
|
[[data-streams-explain-lifecycle-desc]]
|
|
==== {api-description-title}
|
|
|
|
Retrieves information about the index or data stream's current data stream 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.
|
|
|
|
[[data-streams-explain-lifecycle-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Required, string) Comma-separated list of indices or data streams.
|
|
|
|
[[data-streams-explain-lifecycle-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`include_defaults`::
|
|
(Optional, Boolean) Includes default configurations related to the lifecycle of the target.
|
|
Defaults to `false`.
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
[[data-streams-explain-lifecycle-example]]
|
|
==== {api-examples-title}
|
|
|
|
If you want to retrieve the lifecycle state of all the backing indices of a data stream, you can use the data stream name.
|
|
For simplicity, the following example retrieves the lifecycle state of one backing 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 data stream lifecycle in these tests]
|
|
|
|
If the index is managed by a data stream lifecycle `explain` 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:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"indices": {
|
|
".ds-metrics-2023.03.22-000001": {
|
|
"index" : ".ds-metrics-2023.03.22-000001",
|
|
"managed_by_lifecycle" : 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 data stream lifecycle. If the index is not managed by
|
|
a data stream lifecycle 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).
|
|
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:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"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;\"}" <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.
|