Browse Source

[DOCS] Reinforce connection between rollover and index age (#108588)

shainaraskas 1 year ago
parent
commit
9759823fe8

+ 12 - 5
docs/reference/ilm/actions/ilm-rollover.asciidoc

@@ -7,6 +7,13 @@ Phases allowed: hot.
 Rolls over a target to a new index when the existing index satisfies
 the specified rollover conditions.
 
+[NOTE]
+====
+When an index is rolled over, the previous index's age is updated to reflect the rollover time. 
+This date, rather than the index's `creation_date`, is used in {ilm} 
+`min_age` phase calculations. <<min-age-calculation,Learn more>>.
+====
+
 IMPORTANT: If the rollover action is used on a <<ccr-put-follow,follower index>>,
 policy execution waits until the leader index rolls over (or is
 <<skipping-rollover, otherwise marked complete>>),
@@ -46,11 +53,11 @@ PUT my-index-000001
 [[ilm-rollover-options]]
 ==== Options
 
-A rollover action must specify at least one max_* condition, it may include zero
-or more min_* conditions. An empty rollover action is invalid.
+A rollover action must specify at least one `max_*` condition, it may include zero
+or more `min_*` conditions. An empty rollover action is invalid.
 
-The index will rollover once any max_* condition is satisfied and all
-min_* conditions are satisfied. Note, however, that empty indices are not rolled
+The index will roll over once any `max_*` condition is satisfied and all
+`min_*` conditions are satisfied. Note, however, that empty indices are not rolled
 over by default.
 
 // tag::rollover-conditions[]
@@ -256,7 +263,7 @@ PUT _ilm/policy/my_policy
 ===== Roll over using multiple conditions
 
 When you specify multiple rollover conditions,
-the index is rolled over when _any_ of the max_* and _all_ of the min_* conditions are met.
+the index is rolled over when _any_ of the `max_*` and _all_ of the `min_*` conditions are met.
 This example rolls the index over if it is at least 7 days old or at least 100 gigabytes,
 but only as long as the index contains at least 1000 documents.
 

+ 2 - 1
docs/reference/ilm/error-handling.asciidoc

@@ -154,11 +154,12 @@ You can use the <<ilm-explain-lifecycle,{ilm-init} Explain API>> to monitor the
 === Common {ilm-init} setting issues
 
 [discrete]
+[[min-age-calculation]]
 ==== How `min_age` is calculated
 
 When setting up an <<set-up-lifecycle-policy,{ilm-init} policy>> or <<getting-started-index-lifecycle-management,automating rollover with {ilm-init}>>, be aware that `min_age` can be relative to either the rollover time or the index creation time.
 
-If you use <<ilm-rollover,{ilm-init} rollover>>, `min_age` is calculated relative to the time the index was rolled over. This is because the <<indices-rollover-index,rollover API>> generates a new index. The `creation_date` of the new index (retrievable via <<indices-get-settings>>) is used in the calculation. If you do not use rollover in the {ilm-init} policy, `min_age` is calculated relative to the `creation_date` of the original index.
+If you use <<ilm-rollover,{ilm-init} rollover>>, `min_age` is calculated relative to the time the index was rolled over. This is because the <<indices-rollover-index,rollover API>> generates a new index and updates the `age` of the previous index to reflect the rollover time. If the index hasn't been rolled over, then the `age` is the same as the `creation_date` for the index.
 
 You can override how `min_age` is calculated using the `index.lifecycle.origination_date` and `index.lifecycle.parse_origination_date` <<ilm-settings,{ilm-init} settings>>.
 

+ 6 - 0
docs/reference/ilm/ilm-index-lifecycle.asciidoc

@@ -43,6 +43,12 @@ a "cold" phase with a minimum age either unset, or >= 10 days.
 The minimum age defaults to zero, which causes {ilm-init} to move indices to the next phase
 as soon as all actions in the current phase complete.
 
+[NOTE]
+====
+If an index has been <<ilm-rollover,rolled over>>, then the `min_age` value is relative to the time 
+the index was rolled over, not the index creation time. <<min-age-calculation,Learn more>>.
+====
+
 If an index has unallocated shards and the <<cluster-health,cluster health status>> is yellow,
 the index can still transition to the next phase according to its {ilm} policy.
 However, because {es} can only perform certain clean up tasks on a green

+ 1 - 1
docs/reference/ilm/ilm-tutorial.asciidoc

@@ -57,7 +57,7 @@ reaches either a `max_primary_shard_size` of 50 gigabytes or a `max_age` of 30 d
 
 [NOTE]
 ====
-The `min_age` value is relative to the rollover time, not the index creation time.
+The `min_age` value is relative to the rollover time, not the index creation time. <<min-age-calculation,Learn more>>.
 ====
 
 You can create the policy through {kib} or with the

+ 10 - 4
docs/reference/ilm/index-rollover.asciidoc

@@ -3,8 +3,7 @@
 
 When indexing time series data like logs or metrics, you can't write to a single index indefinitely. 
 To meet your indexing and search performance requirements and manage resource usage, 
-you write to an index until some threshold is met and 
-then create a new index and start writing to it instead. 
+you write to an index until some threshold is met and then create a new index and start writing to it instead. 
 Using rolling indices enables you to:
 
 * Optimize the active index for high ingest rates on high-performance _hot_ nodes.
@@ -35,8 +34,15 @@ more configuration steps and concepts:
 You optimize this configuration for ingestion, typically using as many shards as you have hot nodes.
 * An _index alias_ that references the entire set of indices. 
 * A single index designated as the _write index_.
-This is the active index that handles all write requests.
-On each rollover, the new index becomes the write index.
+This is the active index that handles all write requests. 
+On each rollover, the new index becomes the write index. 
+
+[NOTE]
+====
+When an index is rolled over, the previous index's age is updated to reflect the rollover time. 
+This date, rather than the index's `creation_date`, is used in {ilm} 
+`min_age` phase calculations. <<min-age-calculation,Learn more>>.
+====
 
 [discrete]
 [[ilm-automatic-rollover]]