[DOCS] Reformat index stats API docs (#46322)

docs/reference/cluster/nodes-stats.asciidoc

@@ -113,25 +113,15 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
 [[cluster-nodes-stats-api-query-params]]
 ==== {api-query-parms-title}
 
-`completion_fields`::
-    (Optional, string) A comma-separated list of fields for `fielddata` and 
-    `suggest` index metric (supports wildcards).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=completion-fields]
 
-`fielddata_fields`::
-    (Optional, string) A comma-separated list of fields for `fielddata` index 
-    metric (supports wildcards).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=fielddata-fields]
 
-`fields`::
-    (Optional, string) A comma-separated list of fields for `fielddata` and 
-    `completion` index metric (supports wildcards).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=fields]
 
-`groups`::
-    (Optional, string) A comma-separated list of search groups for `search` 
-    index metric.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=groups]
 
-`level`::
-    (Optional, string) Returns indices stats aggregated at index, node or shard 
-    level. Supported options: `indices`, `node`, `shards`.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=level]
 
 `types`::
     (Optional, string) A comma-separated list of document types for the 
@@ -139,10 +129,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-`include_segment_file_sizes`::
-    (Optional, boolean) If `true`, the call reports the aggregated disk usage of 
-    each one  of the Lucene index files (only applies if segment stats are 
-    requested). Defaults to `false`.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-segment-file-sizes]
 
 
 [[cluster-nodes-stats-api-response-body]]

docs/reference/indices/stats.asciidoc

@@ -1,98 +1,138 @@
 [[indices-stats]]
-=== Indices Stats
+=== Index stats API
+++++
+<titleabbrev>Index stats</titleabbrev>
+++++
 
-Indices level stats provide statistics on different operations happening
-on an index. The API provides statistics on the index level scope
-(though most stats can also be retrieved using node level scope).
+Returns statistics for an index.
 
-The following returns high level aggregation and index level stats for
-all indices:
+[source,console]
+----
+GET /twitter/_stats
+----
+// TEST[setup:twitter]
 
-[source,js]
---------------------------------------------------
-GET /_stats
---------------------------------------------------
-// CONSOLE
 
-Specific index stats can be retrieved using:
+[[index-stats-api-request]]
+==== {api-request-title}
 
-[source,js]
---------------------------------------------------
-GET /index1,index2/_stats
---------------------------------------------------
-// CONSOLE
-// TEST[s/^/PUT index1\nPUT index2\n/]
+`GET /<index>/_stats/<index-metric>`
+
+`GET /<index>/_stats`
+
+`GET /_stats`
+
+
+[[index-stats-api-desc]]
+==== {api-description-title}
+
+Use the index stats API to get high-level aggregation and statistics for an index.
+
+By default,
+the returned statistics are index-level
+with `primaries` and `total` aggregations.
+`primaries` are the values for only the primary shards. 
+`total` are the accumulated values for both primary and replica shards.
+
+To get shard-level statistics,
+set the `level` parameter to `shards`.
+
+[NOTE]
+====
+When moving to another node,
+the shard-level statistics for a shard are cleared.
+Although the shard
+is no longer part of the node,
+that node retains any node-level statistics
+to which the shard contributed.
+====
+
+
+[[index-stats-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To retrieve statistics for all indices,
+use a value of `_all` or `*` or omit this parameter.
 
-By default, all stats are returned, returning only specific stats can be
-specified as well in the URI. Those stats can be any of:
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-metric]
 
-[horizontal]
-`docs`:: 		The number of docs / deleted docs (docs not yet merged out).
-				Note, affected by refreshing the index.
 
-`store`:: 		The size of the index.
+[[index-stats-api-query-params]]
+==== {api-query-parms-title}
 
-`indexing`:: 	Indexing statistics, can be combined with a comma
-				separated list of `types` to provide document type level stats.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
 
-`get`:: 		Get statistics, including missing stats.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=fields]
 
-`search`:: 		Search statistics including suggest statistics.
-                You can include statistics for custom groups by adding
-                an extra `groups` parameter (search operations can be associated with one or more
-                groups). The `groups` parameter accepts a comma separated list of group names.
-                Use `_all` to return statistics for all groups.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=completion-fields]
 
-`segments`::    Retrieve the memory use of the open segments. Optionally, setting the `include_segment_file_sizes` flag, report the aggregated disk usage of each one of the Lucene index files.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=fielddata-fields]
 
-`completion`::  Completion suggest statistics.
-`fielddata`::   Fielddata statistics.
-`flush`::       Flush statistics.
-`merge`::       Merge statistics.
-`request_cache`:: <<shard-request-cache,Shard request cache>> statistics.
-`refresh`::     Refresh statistics.
-`warmer`::      Warmer statistics.
-`translog`::    Translog statistics.
+`forbid_closed_indices`::
+(Optional, boolean)
+If `true`, statistics are *not* collected from closed indices.
+Defaults to `true`.
 
-Some statistics allow per field granularity which accepts a list
-comma-separated list of included fields. By default all fields are included:
+include::{docdir}/rest-api/common-parms.asciidoc[tag=groups]
 
-[horizontal]
-`fields`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=level]
 
-    List of fields to be included in the statistics. This is used as the
-    default list unless a more specific field list is provided (see below).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-segment-file-sizes]
 
-`completion_fields`::
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
 
-    List of fields to be included in the Completion Suggest statistics.
 
-`fielddata_fields`::
+[[index-stats-api-example]]
+==== {api-examples-title}
 
-    List of fields to be included in the Fielddata statistics.
 
+[[index-stats-api-multiple-ex]]
+===== Get statistics for multiple indices
 
-Here are some samples:
+[source,console]
+--------------------------------------------------
+GET /index1,index2/_stats
+--------------------------------------------------
+// TEST[s/^/PUT index1\nPUT index2\n/]
+
+
+[[index-stats-api-all-ex]]
+===== Get statistics for all indices
+
+[source,console]
+--------------------------------------------------
+GET /_stats
+--------------------------------------------------
+// TEST[setup:twitter]
+
+
+[[index-stats-api-specific-stats-ex]]
+===== Get specific statistics
 
-[source,js]
+The following request returns
+only the `merge` and `refresh` statistics
+for all indices.
+
+[source,console]
 --------------------------------------------------
-# Get back stats for merge and refresh only for all indices
 GET /_stats/merge,refresh
-# Get back stats for type1 and type2 documents for the my_index index
-GET /my_index/_stats/indexing?types=type1,type2
-# Get back just search stats for group1 and group2
-GET /_stats/search?groups=group1,group2
 --------------------------------------------------
-// CONSOLE
-// TEST[s/^/PUT my_index\n/]
+// TEST[setup:twitter]
 
-The stats returned are aggregated on the index level, with
-`primaries` and `total` aggregations, where `primaries` are the values for only the
-primary shards, and `total` are the accumulated values for both primary and replica shards.
 
-In order to get back shard level stats, set the `level` parameter to `shards`.
+[[index-stats-api-specific-groups-ex]]
+===== Get statistics for specific search groups
 
-Note, as shards move around the cluster, their stats will be cleared as
-they are created on other nodes. On the other hand, even though a shard
-"left" a node, that node will still retain the stats that shard
-contributed to.
+The following request returns
+only search statistics
+for the `group1` and `group2` search groups.
+
+[source,console]
+--------------------------------------------------
+GET /_stats/search?groups=group1,group2
+--------------------------------------------------
+// TEST[setup:twitter]

docs/reference/rest-api/common-parms.asciidoc

@@ -44,6 +44,13 @@ the transaction log so that Elasticsearch is able to replay
 changes on the next start.
 end::committed[]
 
+tag::completion-fields[]
+`completion_fields`::
+(Optional, string)
+Comma-separated list or wildcard expressions of fields
+to include in `fielddata` and `suggest` statistics.
+end::completion-fields[]
+
 tag::default_operator[]
 `default_operator`::
 (Optional, string) The default operator for query string query: AND or OR. 
@@ -89,11 +96,26 @@ Wildcard expressions are not accepted.
 --
 end::expand-wildcards[]
 
-tag::flat-settings[]
-`flat_settings`::
-(Optional, boolean) If `true`, returns settings in flat format. Defaults to
-`false`.
-end::flat-settings[]
+tag::fielddata-fields[]
+`fielddata_fields`::
+(Optional, string)
+Comma-separated list or wildcard expressions of fields
+to include in `fielddata` statistics.
+end::fielddata-fields[]
+
+tag::fields[]
+`fields`::
++
+--
+(Optional, string)
+Comma-separated list or wildcard expressions of fields
+to include in the statistics.
+
+Used as the default list
+unless a specific field list is provided
+in the `completion_fields` or `fielddata_fields` parameters.
+--
+end::fields[]
 
 tag::generation[]
 Generation number, such as `0`. {es} increments this generation number
@@ -108,6 +130,12 @@ If specified,
 the index alias only applies to documents returned by the filter.
 end::index-alias-filter[]
 
+tag::flat-settings[]
+`flat_settings`::
+(Optional, boolean) If `true`, returns settings in flat format. Defaults to
+`false`.
+end::flat-settings[]
+
 tag::http-format[]
 `format`::
 (Optional, string) Short version of the
@@ -120,6 +148,13 @@ tag::from[]
 (Optional, integer) Starting document offset. Defaults to `0`.
 end::from[]
 
+tag::groups[]
+`groups`::
+(Optional, string)
+Comma-separated list of search groups
+to include in the `search` statistics.
+end::groups[]
+
 tag::cat-h[]
 `h`::
 (Optional, string) Comma-separated list of column names to display.
@@ -162,6 +197,14 @@ tag::index-ignore-unavailable[]
 response. Defaults to `false`.
 end::index-ignore-unavailable[]
 
+tag::include-segment-file-sizes[]
+`include_segment_file_sizes`::
+(Optional, boolean)
+If `true`, the call reports the aggregated disk usage of 
+each one  of the Lucene index files (only applies if segment stats are 
+requested). Defaults to `false`.
+end::include-segment-file-sizes[]
+
 tag::include-unloaded-segments[]
 `include_unloaded_segments`::
 (Optional, boolean) If `true`, the response includes information from segments
@@ -174,6 +217,78 @@ tag::index[]
 used to limit the request.
 end::index[]
 
+tag::index-metric[]
+`<index-metric>`::
++
+--
+(Optional, string)
+Comma-separated list of metrics used to limit the request.
+Supported metrics are:
+
+`_all`::
+Return all statistics.
+
+`completion`::
+<<completion-suggester,Completion suggester>> statistics.
+
+`docs`::
+Number of documents and deleted docs, which have not yet merged out.
+<<indices-refresh,Index refreshes>> can affect this statistic.
+
+`fielddata`::
+<<fielddata,Fielddata>> statistics.
+
+`flush`::
+<<indices-flush,Flush>> statistics.
+
+`get`::
+Get statistics,
+including missing stats.
+
+`indexing`::
+<<docs-index_,Indexing>> statistics.
+
+`merge`::
+<<index-modules-merge,Merge>> statistics.
+
+`query_cache`::
+<<query-cache,Query cache>> statistics.
+
+`refresh`::
+<<indices-refresh,Refresh>> statistics.
+
+`request_cache`::
+<<shard-request-cache,Shard request cache>> statistics.
+
+`search`::
+Search statistics including suggest statistics.
+You can include statistics for custom groups
+by adding an extra `groups` parameter
+(search operations can be associated with one or more groups).
+The `groups` parameter accepts a comma separated list of group names.
+Use `_all` to return statistics for all groups.
+
+`segments`::
+Memory use of all open segments.
++
+If the `include_segment_file_sizes` parameter is `true`,
+this metric includes the aggregated disk usage
+of each Lucene index file.
+
+`store`::
+Size of the index in <<byte-units, byte units>>.
+
+`suggest`::
+<<search-suggesters,Suggester>> statistics.
+
+`translog`::
+<<index-modules-translog,Translog>> statistics.
+
+`warmer`::
+<<indices-warmers,Warmer>> statistics.
+--
+end::index-metric[]
+
 tag::index-template[]
 `<index-template>`::
 (Required, string)
@@ -187,6 +302,22 @@ tag::lenient[]
 providing text to a numeric field) will be ignored. Defaults to `false`.
 end::lenient[]
 
+tag::level[]
+`level`::
++
+--
+(Optional, string)
+Indicates whether statistics are aggregated
+at the cluster, index, or shard level.
+
+Valid values are:
+
+*   `cluster`
+*   `indices`
+*   `shards`
+--
+end::level[]
+
 tag::local[]
 `local`::
 (Optional, boolean) If `true`, the request retrieves information from the local