From d2c5a4c5e9b8dc598c5f74bbea74acd1893630f5 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 8 Jul 2020 14:04:14 -0400 Subject: [PATCH] [7.x] [DOCS] Update get data stream API response (#59197) (#59221) Updates docs and snippets for changes made to the get data stream API with PR #59128. --- .../change-mappings-and-settings.asciidoc | 52 ++++-- .../set-up-a-data-stream.asciidoc | 115 ++++++------ .../indices/get-data-stream.asciidoc | 172 ++++++++++++++---- 3 files changed, 220 insertions(+), 119 deletions(-) diff --git a/docs/reference/data-streams/change-mappings-and-settings.asciidoc b/docs/reference/data-streams/change-mappings-and-settings.asciidoc index e0da33322d854..da797110a4b28 100644 --- a/docs/reference/data-streams/change-mappings-and-settings.asciidoc +++ b/docs/reference/data-streams/change-mappings-and-settings.asciidoc @@ -84,6 +84,8 @@ PUT /_index_template/new_logs_data_stream PUT /_data_stream/logs +POST /logs/_rollover/ + PUT /_data_stream/new_logs ---- // TESTSETUP @@ -565,33 +567,43 @@ data stream, including a list of its backing indices. ---- GET /_data_stream/logs ---- -// TEST[skip: shard failures] The API returns the following response. Note the `indices` property contains an -array of the stream's current backing indices. The oldest backing index, -`.ds-logs-000001`, is the first item in the array. +array of the stream's current backing indices. The first item in the array +contains information about the stream's oldest backing index, `.ds-logs-000001`. [source,console-result] ---- -[ - { - "name": "logs", - "timestamp_field": "@timestamp", - "indices": [ - { - "index_name": ".ds-logs-000001", - "index_uuid": "DXAE-xcCQTKF93bMm9iawA" +{ + "data_streams": [ + { + "name": "logs", + "timestamp_field": { + "name": "@timestamp" }, - { - "index_name": ".ds-logs-000002", - "index_uuid": "Wzxq0VhsQKyPxHhaK3WYAg" - } - ], - "generation": 2 - } -] + "indices": [ + { + "index_name": ".ds-logs-000001", <1> + "index_uuid": "Gpdiyq8sRuK9WuthvAdFbw" + }, + { + "index_name": ".ds-logs-000002", + "index_uuid": "_eEfRrFHS9OyhqWntkgHAQ" + } + ], + "generation": 2, + "status": "GREEN", + "template": "logs_data_stream" + } + ] +} ---- -// TESTRESPONSE[skip:unable to assert responses with top level array] +// TESTRESPONSE[s/"index_uuid": "Gpdiyq8sRuK9WuthvAdFbw"/"index_uuid": $body.data_streams.0.indices.0.index_uuid/] +// TESTRESPONSE[s/"index_uuid": "_eEfRrFHS9OyhqWntkgHAQ"/"index_uuid": $body.data_streams.0.indices.1.index_uuid/] +// TESTRESPONSE[s/"status": "GREEN"/"status": "YELLOW"/] + +<1> First item in the `indices` array for the `logs` data stream. This item +contains information about the stream's oldest backing index, `.ds-logs-000001`. The following <> request copies documents from `.ds-logs-000001` to the `new_logs` data stream. Note the request's `op_type` is diff --git a/docs/reference/data-streams/set-up-a-data-stream.asciidoc b/docs/reference/data-streams/set-up-a-data-stream.asciidoc index a8385a065058b..77f8c91a9563e 100644 --- a/docs/reference/data-streams/set-up-a-data-stream.asciidoc +++ b/docs/reference/data-streams/set-up-a-data-stream.asciidoc @@ -278,20 +278,6 @@ PUT /_data_stream/logs_alt ==== -- -//// -[source,console] ----- -DELETE /_data_stream/logs - -DELETE /_data_stream/logs_alt - -DELETE /_index_template/logs_data_stream - -DELETE /_ilm/policy/logs_policy ----- -// TEST[continued] -//// - [discrete] [[get-info-about-a-data-stream]] === Get information about a data stream @@ -303,47 +289,70 @@ information about one or more data streams, including: * The current backing indices, which is returned as an array. The last item in the array contains information about the stream's current write index. * The current generation +* The data stream's health status +* The index template used to create the stream's backing indices +* The current {ilm-init} lifecycle policy in the stream's matching index +template This is also handy way to verify that a recently created data stream exists. .*Example* [%collapsible] ==== -The following get data stream API request retrieves information about any data -streams starting with `logs`. +The following get data stream API request retrieves information about the +`logs` data stream. + +//// +[source,console] +---- +POST /logs/_rollover/ +---- +// TEST[continued] +//// [source,console] ---- -GET /_data_stream/logs* +GET /_data_stream/logs ---- -// TEST[skip: shard failures] +// TEST[continued] -The API returns the following response, which includes information about the -`logs` data stream. Note the `indices` property contains an array of the -stream's current backing indices. The last item in this array contains -information for the `logs` stream's write index, `.ds-logs-000002`. +The API returns the following response. Note the `indices` property contains an +array of the stream's current backing indices. The last item in this array +contains information about the stream's write index, `.ds-logs-000002`. [source,console-result] ---- -[ - { - "name": "logs", - "timestamp_field": "@timestamp", - "indices": [ - { - "index_name": ".ds-logs-000001", - "index_uuid": "DXAE-xcCQTKF93bMm9iawA" +{ + "data_streams": [ + { + "name": "logs", + "timestamp_field": { + "name": "@timestamp" }, - { - "index_name": ".ds-logs-000002", - "index_uuid": "Wzxq0VhsQKyPxHhaK3WYAg" - } - ], - "generation": 2 - } -] + "indices": [ + { + "index_name": ".ds-logs-000001", + "index_uuid": "krR78LfvTOe6gr5dj2_1xQ" + }, + { + "index_name": ".ds-logs-000002", <1> + "index_uuid": "C6LWyNJHQWmA08aQGvqRkA" + } + ], + "generation": 2, + "status": "GREEN", + "template": "logs_data_stream", + "ilm_policy": "logs_policy" + } + ] +} ---- -// TESTRESPONSE[skip:unable to assert responses with top level array] +// TESTRESPONSE[s/"index_uuid": "krR78LfvTOe6gr5dj2_1xQ"/"index_uuid": $body.data_streams.0.indices.0.index_uuid/] +// TESTRESPONSE[s/"index_uuid": "C6LWyNJHQWmA08aQGvqRkA"/"index_uuid": $body.data_streams.0.indices.1.index_uuid/] +// TESTRESPONSE[s/"status": "GREEN"/"status": "YELLOW"/] + +<1> Last item in the `indices` array for the `logs` data stream. This item +contains information about the stream's current write index, `.ds-logs-000002`. ==== [discrete] @@ -366,30 +375,6 @@ a data stream and its backing indices. The following delete data stream API request deletes the `logs` data stream. This request also deletes the stream's backing indices and any data they contain. -//// -[source,console] ----- -PUT /_index_template/logs_data_stream -{ - "index_patterns": [ "logs*" ], - "data_stream": { - "timestamp_field": "@timestamp" - }, - "template": { - "mappings": { - "properties": { - "@timestamp": { - "type": "date" - } - } - } - } -} - -PUT /_data_stream/logs ----- -//// - [source,console] ---- DELETE /_data_stream/logs @@ -400,7 +385,9 @@ DELETE /_data_stream/logs //// [source,console] ---- -DELETE /_index_template/logs_data_stream +DELETE /_data_stream/* +DELETE /_index_template/* +DELETE /_ilm/policy/logs_policy ---- // TEST[continued] //// diff --git a/docs/reference/indices/get-data-stream.asciidoc b/docs/reference/indices/get-data-stream.asciidoc index 3250c7167cedd..8689bf345f086 100644 --- a/docs/reference/indices/get-data-stream.asciidoc +++ b/docs/reference/indices/get-data-stream.asciidoc @@ -10,9 +10,33 @@ See <>. //// [source,console] ---- -PUT _index_template/template +PUT /_ilm/policy/my-lifecycle-policy { - "index_patterns": ["my-data-stream*"], + "policy": { + "phases": { + "hot": { + "actions": { + "rollover": { + "max_size": "25GB" + } + } + }, + "delete": { + "min_age": "30d", + "actions": { + "delete": {} + } + } + } + } +} + +PUT /_index_template/my-index-template +{ + "index_patterns": [ "my-data-stream*" ], + "data_stream": { + "timestamp_field": "@timestamp" + }, "template": { "mappings": { "properties": { @@ -20,14 +44,18 @@ PUT _index_template/template "type": "date" } } + }, + "settings": { + "index.lifecycle.name": "my-lifecycle-policy" } - }, - "data_stream": { - "timestamp_field": "@timestamp" } } PUT /_data_stream/my-data-stream + +POST /my-data-stream/_rollover + +PUT /_data_stream/my-data-stream_two ---- // TESTSETUP //// @@ -35,8 +63,9 @@ PUT /_data_stream/my-data-stream //// [source,console] ---- -DELETE /_data_stream/my-data-stream -DELETE /_index_template/template +DELETE /_data_stream/* +DELETE /_index_template/* +DELETE /_ilm/policy/my-lifecycle-policy ---- // TEARDOWN //// @@ -45,7 +74,6 @@ DELETE /_index_template/template ---- GET /_data_stream/my-data-stream ---- -// TEST[skip_shard_failures] [[get-data-stream-api-request]] ==== {api-request-title} @@ -64,14 +92,29 @@ Wildcard (`*`) expressions are supported. [[get-data-stream-api-response-body]] ==== {api-response-body-title} +`data_streams`:: +(array of objects) +Contains information about retrieved data streams. ++ +.Properties of objects in `data_streams` +[%collapsible%open] +==== `name`:: (string) Name of the data stream. `timestamp_field`:: +(object) +Contains information about the data stream's timestamp field. ++ +.Properties of `timestamp_field` +[%collapsible%open] +===== +`name`:: (string) Name of the data stream's timestamp field. This field must be included in every document indexed to the data stream. +===== `indices`:: (array of objects) @@ -83,7 +126,7 @@ The last item in this array contains information about the stream's current + .Properties of `indices` objects [%collapsible%open] -==== +===== `index_name`:: (string) Name of the backing index. For naming conventions, see @@ -92,7 +135,7 @@ Name of the backing index. For naming conventions, see `index_uuid`:: (string) Universally unique identifier (UUID) for the index. -==== +===== `generation`:: (integer) @@ -100,6 +143,47 @@ Current <> for the data stream. This number acts as a cumulative count of the stream's backing indices, including deleted indices. +`status`:: +(string) +<> of the data stream. ++ +This health status is based on the state of the primary and replica shards of +the stream's backing indices. ++ +.Values for `status` +[%collapsible%open] +===== +`green`::: +All shards are assigned. + +`yellow`::: +All primary shards are assigned, but one or more replica shards are +unassigned. + +`red`::: +One or more primary shards are unassigned, so some data is unavailable. +===== + +`template`:: +(string) +Name of the index template used to create the data stream's backing indices. ++ +The template's index pattern must match the name of this data stream. See +<>. + +`ilm_policy`:: +(string) +Name of the current {ilm-init} lifecycle policy in the stream's matching index +template. This lifecycle policy is set in the `index.lifecycle.name` setting. ++ +If the template does not include a lifecycle policy, this property is not +included in the response. ++ +NOTE: A data stream's backing indices may be assigned different lifecycle +policies. To retrieve the lifecycle policy for individual backing indices, +use the <>. +==== + [[get-data-stream-api-example]] ==== {api-examples-title} @@ -107,35 +191,53 @@ deleted indices. ---- GET _data_stream/my-data-stream* ---- -// TEST[continued] -// TEST[skip_shard_failures] The API returns the following response: [source,console-result] ---- -[ - { - "name" : "my-data-stream", <1> - "timestamp_field" : "@timestamp", <2> - "indices" : [ <3> - { - "index_name" : ".ds-my-data-stream-000001", - "index_uuid" : "DXAE-xcCQTKF93bMm9iawA" +{ + "data_streams": [ + { + "name": "my-data-stream", + "timestamp_field": { + "name": "@timestamp" }, - { - "index_name" : ".ds-my-data-stream-000002", - "index_uuid" : "Wzxq0VhsQKyPxHhaK3WYAg" - } - ], - "generation" : 2 <4> - } -] + "indices": [ + { + "index_name": ".ds-my-data-stream-000001", + "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg" + }, + { + "index_name": ".ds-my-data-stream-000002", + "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw" + } + ], + "generation": 2, + "status": "GREEN", + "template": "my-index-template", + "ilm_policy": "my-lifecycle-policy" + }, + { + "name": "my-data-stream_two", + "timestamp_field": { + "name": "@timestamp" + }, + "indices": [ + { + "index_name": ".ds-my-data-stream_two-000001", + "index_uuid": "3liBu2SYS5axasRt6fUIpA" + } + ], + "generation": 1, + "status": "YELLOW", + "template": "my-index-template", + "ilm_policy": "my-lifecycle-policy" + } + ] +} ---- -// TESTRESPONSE[skip:unable to assert responses with top level array] - -<1> Name of the data stream -<2> The name of the timestamp field for the data stream -<3> List of backing indices -<4> Current generation for the data stream - +// TESTRESPONSE[s/"index_uuid": "xCEhwsp8Tey0-FLNFYVwSg"/"index_uuid": $body.data_streams.0.indices.0.index_uuid/] +// TESTRESPONSE[s/"index_uuid": "PA_JquKGSiKcAKBA8DJ5gw"/"index_uuid": $body.data_streams.0.indices.1.index_uuid/] +// TESTRESPONSE[s/"index_uuid": "3liBu2SYS5axasRt6fUIpA"/"index_uuid": $body.data_streams.1.indices.0.index_uuid/] +// TESTRESPONSE[s/"status": "GREEN"/"status": "YELLOW"/]