mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
322805858f
This adds a new index privilege called `manage_dlm`. The `manage_dlm` has permission to perform all DLM actions on an index, including put and delete. It also adds the ability to call DLM get and explain to the `view_index_metadata` existing index privilege.
119 lines
4.5 KiB
Text
119 lines
4.5 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.
|
|
|
|
[[explain-lifecycle-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* Nit: would rephrase as:
|
|
|
|
If the {es} {security-features} are enabled, you must have at least the `manage_dlm` index privilege or
|
|
`view_index_metadata` index privilege to use this API. For more information, see <<security-privileges>>.
|
|
|
|
[[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).
|
|
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_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.
|