From da531f4cf61092bf470cd27c24deafd18cd1b0b2 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 3 Apr 2020 11:58:25 -0700 Subject: [PATCH] [DOCS] Collapse nested objects in CCR APIs (#54697) --- .../ccr/apis/follow/get-follow-info.asciidoc | 141 ++++++------ .../ccr/apis/follow/get-follow-stats.asciidoc | 213 +++++++++--------- .../reference/ccr/apis/get-ccr-stats.asciidoc | 56 ++--- 3 files changed, 212 insertions(+), 198 deletions(-) diff --git a/docs/reference/ccr/apis/follow/get-follow-info.asciidoc b/docs/reference/ccr/apis/follow/get-follow-info.asciidoc index 8361f7911fe06..e26fdb803cde5 100644 --- a/docs/reference/ccr/apis/follow/get-follow-info.asciidoc +++ b/docs/reference/ccr/apis/follow/get-follow-info.asciidoc @@ -57,77 +57,84 @@ replication options and whether the follower indices are active or paused. ``:: (Required, string) A comma-delimited list of follower index patterns. +[role="child_attributes"] [[ccr-get-follow-info-response-body]] ==== {api-response-body-title} -This API returns the following information: - +//Begin follower_indices `follower_indices`:: - (array) An array of follower index statistics. - -The `indices` array consists of objects containing several fields: - -`indices[].follower_index`:: - (string) The name of the follower index. - -`indices[].remote_cluster`:: - (string) The <> that contains the - leader index. - -`indices[].leader_index`:: - (string) The name of the index in the leader cluster that is followed. - -`indices[].status`:: - (string) Whether index following is `active` or `paused`. - -`indices[].parameters`:: - (object) An object that encapsulates {ccr} parameters. - -The `parameters` contains the following fields: - -`indices[].parameters.max_read_request_operation_count`:: - (integer) The maximum number of operations to pull per read from the remote - cluster. - -`indices[].parameters.max_outstanding_read_requests`:: - (long) The maximum number of outstanding read requests from the remote cluster. - -`indices[].parameters.max_read_request_size`:: - (<>) The maximum size in bytes of per read of a batch - of operations pulled from the remote cluster. - -`indices[].parameters.max_write_request_operation_count`:: - (integer) The maximum number of operations per bulk write request executed on - the follower. - -`indices[].parameters.max_write_request_size`:: - (<>) The maximum total bytes of operations per bulk - write request executed on the follower. - -`indices[].parameters.max_outstanding_write_requests`:: - (integer) The maximum number of outstanding write requests on the follower. - -`indices[].parameters.max_write_buffer_count`:: - (integer) The maximum number of operations that can be queued for writing. - When this limit is reached, reads from the remote cluster are deferred until - the number of queued operations goes below the limit. - -`indices[].parameters.max_write_buffer_size`:: - (<>) The maximum total bytes of operations that can be - queued for writing. When this limit is reached, reads from the remote cluster - are deferred until the total bytes of queued operations goes below the limit. - -`indices[].parameters.max_retry_delay`:: - (<>) The maximum time to wait before retrying an - operation that failed exceptionally. An exponential backoff strategy is - employed when retrying. - -`indices[].parameters.read_poll_timeout`:: - (<>) The maximum time to wait for new operations on the - remote cluster when the follower index is synchronized with the leader index. - When the timeout has elapsed, the poll for operations returns to the follower - so that it can update some statistics, then the follower immediately attempts - to read from the leader again. +(array) An array of follower index statistics. ++ +.Properties of objects in `follower_indices` +[%collapsible%open] +==== +`follower_index`:: +(string) The name of the follower index. + +`leader_index`:: +(string) The name of the index in the leader cluster that is followed. + +//Begin parameters +`parameters`:: +(object) An object that encapsulates {ccr} parameters. ++ +.Properties of `parameters` +[%collapsible%open] +===== +`max_outstanding_read_requests`:: +(long) The maximum number of outstanding read requests from the remote cluster. + +`max_outstanding_write_requests`:: +(integer) The maximum number of outstanding write requests on the follower. + +`max_read_request_operation_count`:: +(integer) The maximum number of operations to pull per read from the remote +cluster. + +`max_read_request_size`:: +(<>) The maximum size in bytes of per read of a batch of +operations pulled from the remote cluster. + +`max_retry_delay`:: +(<>) The maximum time to wait before retrying an +operation that failed exceptionally. An exponential backoff strategy is employed +when retrying. + +`max_write_buffer_count`:: +(integer) The maximum number of operations that can be queued for writing. When +this limit is reached, reads from the remote cluster are deferred until the +number of queued operations goes below the limit. + +`max_write_buffer_size`:: +(<>) The maximum total bytes of operations that can be +queued for writing. When this limit is reached, reads from the remote cluster +are deferred until the total bytes of queued operations goes below the limit. + +`max_write_request_operation_count`:: +(integer) The maximum number of operations per bulk write request executed on +the follower. + +`max_write_request_size`:: +(<>) The maximum total bytes of operations per bulk write +request executed on the follower. + +`read_poll_timeout`:: +(<>) The maximum time to wait for new operations on the +remote cluster when the follower index is synchronized with the leader index. +When the timeout has elapsed, the poll for operations returns to the follower so +that it can update some statistics, then the follower immediately attempts +to read from the leader again. +===== +//End parameters + +`remote_cluster`:: +(string) The <> that contains the +leader index. + +`status`:: +(string) Whether index following is `active` or `paused`. +==== +//End follower_indices [[ccr-get-follow-info-examples]] ==== {api-examples-title} diff --git a/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc b/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc index 49dc776a6d301..c3017d74bd8b1 100644 --- a/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc +++ b/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc @@ -57,145 +57,150 @@ following tasks associated with each shard for the specified indices. ``:: (Required, string) A comma-delimited list of index patterns. +[role="child_attributes"] [[ccr-get-follow-stats-response-body]] ==== {api-response-body-title} -This API returns the following information: - +//Begin indices `indices`:: - (array) An array of follower index statistics. - -The `indices` array consists of objects containing two fields: - -`indices[].index`:: - (string) The name of the follower index. - -`indices[].shards`:: - (array) An array of shard-level following task statistics. - -The `shards` array consists of objects containing the following fields: - -`indices[].shards[].remote_cluster`:: - (string) The <> containing the leader - index. - -`indices[].shards[].leader_index`:: - (string) The name of the index in the leader cluster being followed. - -`indices[].shards[].follower_index`:: - (string) The name of the follower index. +(array) An array of follower index statistics. ++ +.Properties of `indices` +[%collapsible%open] +==== +`fatal_exception`:: +(object) An object representing a fatal exception that cancelled the following +task. In this situation, the following task must be resumed manually with the +<>. + +`index`:: +(string) The name of the follower index. + +//Begin shards +`shards`:: +(array) An array of shard-level following task statistics. ++ +.Properties of objects in `shards` +[%collapsible%open] +===== +`bytes_read`:: +(long) The total of transferred bytes read from the leader. ++ +-- +NOTE: This is only an estimate and does not account for compression if enabled. -`indices[].shards[].shard_id`:: - (integer) The numerical shard ID, with values from 0 to one less than the - number of replicas. +-- -`indices[].shards[].leader_global_checkpoint`:: - (long) The current global checkpoint on the leader known to the follower task. +`failed_read_requests`:: +(long) The number of failed reads. -`indices[].shards[].leader_max_seq_no`:: - (long) The current maximum sequence number on the leader known to the follower - task. +failed_write_requests`:: +(long) The number of failed bulk write requests executed on the follower. -`indices[].shards[].follower_global_checkpoint`:: - (long) The current global checkpoint on the follower. The difference between the - `leader_global_checkpoint` and the `follower_global_checkpoint` is an - indication of how much the follower is lagging the leader. +`follower_aliases_version`:: +(long) The index aliases version the follower is synced up to. -`indices[].shards[].follower_max_seq_no`:: - (long) The current maximum sequence number on the follower. +`follower_global_checkpoint`:: +(long) The current global checkpoint on the follower. The difference between the +`leader_global_checkpoint` and the `follower_global_checkpoint` is an +indication of how much the follower is lagging the leader. -`indices[].shards[].last_requested_seq_no`:: - (long) The starting sequence number of the last batch of operations requested - from the leader. +`follower_index`:: +(string) The name of the follower index. -`indices[].shards[].outstanding_read_requests`:: - (integer) The number of active read requests from the follower. +`follower_mapping_version`:: +(long) The mapping version the follower is synced up to. -`indices[].shards[].outstanding_write_requests`:: - (integer) The number of active bulk write requests on the follower. +`follower_max_seq_no`:: +(long) The current maximum sequence number on the follower. -`indices[].shards[].write_buffer_operation_count`:: - (integer) The number of write operations queued on the follower. +`follower_settings_version`:: +(long) The index settings version the follower is synced up to. -`indices[].shards[].follower_mapping_version`:: - (long) The mapping version the follower is synced up to. +`last_requested_seq_no`:: +(long) The starting sequence number of the last batch of operations requested +from the leader. -`indices[].shards[].follower_settings_version`:: - (long) The index settings version the follower is synced up to. +`leader_global_checkpoint`:: +(long) The current global checkpoint on the leader known to the follower task. -`indices[].shards[].follower_aliases_version`:: - (long) The index aliases version the follower is synced up to. +`leader_index`:: +(string) The name of the index in the leader cluster being followed. -`indices[].shards[].total_read_time_millis`:: - (long) The total time reads were outstanding, measured from the time a read - was sent to the leader to the time a reply was returned to the follower. +`leader_max_seq_no`:: +(long) The current maximum sequence number on the leader known to the follower +task. -`indices[].shards[].total_read_remote_exec_time_millis`:: - (long) The total time reads spent executing on the remote cluster. +`operations_read`:: +(long) The total number of operations read from the leader. -`indices[].shards[].successful_read_requests`:: - (long) The number of successful fetches. +operations_written`:: +(long) The number of operations written on the follower. -`indices[].shards[].failed_read_requests`:: - (long) The number of failed reads. +`outstanding_read_requests`:: +(integer) The number of active read requests from the follower. -`indices[].shards[].operations_read`:: - (long) The total number of operations read from the leader. +`outstanding_write_requests`:: +(integer) The number of active bulk write requests on the follower. -`indices[].shards[].bytes_read`:: - (long) The total of transferred bytes read from the leader. +//Begin read_exceptions +`read_exceptions`:: +(array) An array of objects representing failed reads. + --- -NOTE: This is only an estimate and does not account for compression if enabled. - --- +.Properties of objects in `read_exceptions` +[%collapsible%open] +====== +`exception`:: +(object) Represents the exception that caused the read to fail. -`indices[].shards[].total_write_time_millis`:: - (long) The total time spent writing on the follower. +`from_seq_no`:: +(long) The starting sequence number of the batch requested from the leader. -`indices[].shards[].write_buffer_size_in_bytes`:: - (long) The total number of bytes of operations currently queued for writing. +`retries`:: +(integer) The number of times the batch has been retried. +====== +//End read_exceptions -`indices[].shards[].successful_write_requests`:: - (long) The number of bulk write requests executed on the follower. +`remote_cluster`:: +(string) The <> containing the leader +index. -`indices[].shards[].failed_write_requests`:: - (long) The number of failed bulk write requests executed on the follower. +`shard_id`:: +(integer) The numerical shard ID, with values from 0 to one less than the +number of replicas. -`indices[].shards[].operations_written`:: - (long) The number of operations written on the follower. +`successful_read_requests`:: +(long) The number of successful fetches. -`indices[].shards[].read_exceptions`:: - (array) An array of objects representing failed reads. +`successful_write_requests`:: +(long) The number of bulk write requests executed on the follower. -The `read_exceptions` array consists of objects containing the following -fields: - -`indices[].shards[].read_exceptions[].from_seq_no`:: - (long) The starting sequence number of the batch requested from the leader. - -`indices[].shards[].read_exceptions[].retries`:: - (integer) The number of times the batch has been retried. +`time_since_last_read_millis`:: +(long) The number of milliseconds since a read request was sent to the leader. ++ +NOTE: When the follower is caught up to the leader, this number will increase up +to the configured `read_poll_timeout` at which point another read request will +be sent to the leader. -`indices[].shards[].read_exceptions[].exception`:: - (object) Represents the exception that caused the read to fail. +`total_read_remote_exec_time_millis`:: +(long) The total time reads spent executing on the remote cluster. -Continuing with the fields from `shards`: +`total_read_time_millis`:: +(long) The total time reads were outstanding, measured from the time a read was +sent to the leader to the time a reply was returned to the follower. -`indices[].shards[].time_since_last_read_millis`:: - (long) The number of milliseconds since a read request was sent to the leader. -+ --- -NOTE: When the follower is caught up to the leader, this number will - increase up to the configured `read_poll_timeout` at which point another read - request will be sent to the leader. +`total_write_time_millis`:: +(long) The total time spent writing on the follower. --- +`write_buffer_operation_count`:: +(integer) The number of write operations queued on the follower. -`indices[].fatal_exception`:: - (object) An object representing a fatal exception that cancelled the following - task. In this situation, the following task must be resumed manually with the - <>. +write_buffer_size_in_bytes`:: +(long) The total number of bytes of operations currently queued for writing. +===== +//End shards +==== +//End indices [[ccr-get-follow-stats-examples]] ==== {api-examples-title} diff --git a/docs/reference/ccr/apis/get-ccr-stats.asciidoc b/docs/reference/ccr/apis/get-ccr-stats.asciidoc index 564840eb179d5..4f781bce6e640 100644 --- a/docs/reference/ccr/apis/get-ccr-stats.asciidoc +++ b/docs/reference/ccr/apis/get-ccr-stats.asciidoc @@ -51,39 +51,41 @@ This API gets {ccr} stats. This API will return all stats related to {ccr}. In particular, this API returns stats about auto-following, and returns the same shard-level stats as in the <>. +[role="child_attributes"] [[ccr-get-stats-response-body]] ==== {api-response-body-title} -This API returns the following information: - +//Begin auto_follow_stats `auto_follow_stats`:: - (object) An object representing stats for the auto-follow coordinator. - -This object consists of the following fields: - -`auto_follow_stats.number_of_failed_follow_indices`:: - (long) The number of indices that the auto-follow coordinator failed to - automatically follow. The causes of recent failures are captured in the logs - of the elected master node and in the - `auto_follow_stats.recent_auto_follow_errors` field. - -`auto_follow_stats.number_of_failed_remote_cluster_state_requests`:: - (long) The number of times that the auto-follow coordinator failed to retrieve - the cluster state from a remote cluster registered in a collection of - auto-follow patterns. - -`auto_follow_stats.number_of_successful_follow_indices`:: - (long) The number of indices that the auto-follow coordinator successfully - followed. - -`auto_follow_stats.recent_auto_follow_errors`:: - (array) An array of objects representing failures by the auto-follow - coordinator. +(object) An object representing stats for the auto-follow coordinator. ++ +.Properties of `auto_follow_stats` +[%collapsible%open] +==== +`number_of_failed_follow_indices`:: +(long) The number of indices that the auto-follow coordinator failed to +automatically follow. The causes of recent failures are captured in the logs +of the elected master node and in the +`auto_follow_stats.recent_auto_follow_errors` field. + +`number_of_failed_remote_cluster_state_requests`:: +(long) The number of times that the auto-follow coordinator failed to retrieve +the cluster state from a remote cluster registered in a collection of +auto-follow patterns. + +`number_of_successful_follow_indices`:: +(long) The number of indices that the auto-follow coordinator successfully +followed. + +`recent_auto_follow_errors`:: +(array) An array of objects representing failures by the auto-follow coordinator. +==== +//End auto_follow_stats `follow_stats`:: - (object) An object representing shard-level stats for follower indices; refer - to the details of the response in the - <>. +(object) An object representing shard-level stats for follower indices; refer to +the details of the response in the +<>. [[ccr-get-stats-examples]] ==== {api-examples-title}