Skip to content

Commit 39792ea

Browse files
jrodewigjrodewig
authored
[DOCS] Reformat index stats API docs (#46322) (#46415)
1 parent 8b4fe54 commit 39792ea

File tree

3 files changed

+255
-84
lines changed

3 files changed

+255
-84
lines changed

‎docs/reference/cluster/nodes-stats.asciidoc‎

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -113,36 +113,23 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id]
113113
[[cluster-nodes-stats-api-query-params]]
114114
==== {api-query-parms-title}
115115

116-
`completion_fields`::
117-
(Optional, string) A comma-separated list of fields for `fielddata` and
118-
`suggest` index metric (supports wildcards).
116+
include::{docdir}/rest-api/common-parms.asciidoc[tag=completion-fields]
119117

120-
`fielddata_fields`::
121-
(Optional, string) A comma-separated list of fields for `fielddata` index
122-
metric (supports wildcards).
118+
include::{docdir}/rest-api/common-parms.asciidoc[tag=fielddata-fields]
123119

124-
`fields`::
125-
(Optional, string) A comma-separated list of fields for `fielddata` and
126-
`completion` index metric (supports wildcards).
120+
include::{docdir}/rest-api/common-parms.asciidoc[tag=fields]
127121

128-
`groups`::
129-
(Optional, string) A comma-separated list of search groups for `search`
130-
index metric.
122+
include::{docdir}/rest-api/common-parms.asciidoc[tag=groups]
131123

132-
`level`::
133-
(Optional, string) Returns indices stats aggregated at index, node or shard
134-
level. Supported options: `indices`, `node`, `shards`.
124+
include::{docdir}/rest-api/common-parms.asciidoc[tag=level]
135125

136126
`types`::
137127
(Optional, string) A comma-separated list of document types for the
138128
`indexing` index metric.
139129

140130
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
141131

142-
`include_segment_file_sizes`::
143-
(Optional, boolean) If `true`, the call reports the aggregated disk usage of
144-
each one of the Lucene index files (only applies if segment stats are
145-
requested). Defaults to `false`.
132+
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-segment-file-sizes]
146133

147134

148135
[[cluster-nodes-stats-api-response-body]]

‎docs/reference/indices/stats.asciidoc‎

Lines changed: 110 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,143 @@
11
[[indices-stats]]
2-
=== Indices Stats
2+
=== Index stats API
3+
++++
4+
<titleabbrev>Index stats</titleabbrev>
5+
++++
36

4-
Indices level stats provide statistics on different operations happening
5-
on an index. The API provides statistics on the index level scope
6-
(though most stats can also be retrieved using node level scope).
7-
8-
The following returns high level aggregation and index level stats for
9-
all indices:
7+
Returns statistics for an index.
108

119
[source,js]
12-
--------------------------------------------------
13-
GET /_stats
14-
--------------------------------------------------
10+
----
11+
GET /twitter/_stats
12+
----
1513
// CONSOLE
14+
// TEST[setup:twitter]
1615

17-
Specific index stats can be retrieved using:
1816

19-
[source,js]
20-
--------------------------------------------------
21-
GET /index1,index2/_stats
22-
--------------------------------------------------
23-
// CONSOLE
24-
// TEST[s/^/PUT index1\nPUT index2\n/]
17+
[[index-stats-api-request]]
18+
==== {api-request-title}
19+
20+
`GET /<index>/_stats/<index-metric>`
21+
22+
`GET /<index>/_stats`
23+
24+
`GET /_stats`
25+
26+
27+
[[index-stats-api-desc]]
28+
==== {api-description-title}
29+
30+
Use the index stats API to get high-level aggregation and statistics for an index.
31+
32+
By default,
33+
the returned statistics are index-level
34+
with `primaries` and `total` aggregations.
35+
`primaries` are the values for only the primary shards.
36+
`total` are the accumulated values for both primary and replica shards.
37+
38+
To get shard-level statistics,
39+
set the `level` parameter to `shards`.
40+
41+
[NOTE]
42+
====
43+
When moving to another node,
44+
the shard-level statistics for a shard are cleared.
45+
Although the shard
46+
is no longer part of the node,
47+
that node retains any node-level statistics
48+
to which the shard contributed.
49+
====
50+
51+
52+
[[index-stats-api-path-params]]
53+
==== {api-path-parms-title}
54+
55+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
56+
+
57+
To retrieve statistics for all indices,
58+
use a value of `_all` or `*` or omit this parameter.
59+
60+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-metric]
2561

26-
By default, all stats are returned, returning only specific stats can be
27-
specified as well in the URI. Those stats can be any of:
2862

29-
[horizontal]
30-
`docs`:: The number of docs / deleted docs (docs not yet merged out).
31-
Note, affected by refreshing the index.
63+
[[index-stats-api-query-params]]
64+
==== {api-query-parms-title}
3265

33-
`store`:: The size of the index.
66+
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
67+
+
68+
Defaults to `open`.
3469

35-
`indexing`:: Indexing statistics, can be combined with a comma
36-
separated list of `types` to provide document type level stats.
70+
include::{docdir}/rest-api/common-parms.asciidoc[tag=fields]
3771

38-
`get`:: Get statistics, including missing stats.
72+
include::{docdir}/rest-api/common-parms.asciidoc[tag=completion-fields]
3973

40-
`search`:: Search statistics including suggest statistics.
41-
You can include statistics for custom groups by adding
42-
an extra `groups` parameter (search operations can be associated with one or more
43-
groups). The `groups` parameter accepts a comma separated list of group names.
44-
Use `_all` to return statistics for all groups.
74+
include::{docdir}/rest-api/common-parms.asciidoc[tag=fielddata-fields]
4575

46-
`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.
76+
`forbid_closed_indices`::
77+
(Optional, boolean)
78+
If `true`, statistics are *not* collected from closed indices.
79+
Defaults to `true`.
4780

48-
`completion`:: Completion suggest statistics.
49-
`fielddata`:: Fielddata statistics.
50-
`flush`:: Flush statistics.
51-
`merge`:: Merge statistics.
52-
`request_cache`:: <<shard-request-cache,Shard request cache>> statistics.
53-
`refresh`:: Refresh statistics.
54-
`warmer`:: Warmer statistics.
55-
`translog`:: Translog statistics.
81+
include::{docdir}/rest-api/common-parms.asciidoc[tag=groups]
5682

57-
Some statistics allow per field granularity which accepts a list
58-
comma-separated list of included fields. By default all fields are included:
83+
include::{docdir}/rest-api/common-parms.asciidoc[tag=level]
5984

60-
[horizontal]
61-
`fields`::
85+
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-segment-file-sizes]
6286

63-
List of fields to be included in the statistics. This is used as the
64-
default list unless a more specific field list is provided (see below).
87+
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
6588

66-
`completion_fields`::
6789

68-
List of fields to be included in the Completion Suggest statistics.
90+
[[index-stats-api-example]]
91+
==== {api-examples-title}
6992

70-
`fielddata_fields`::
7193

72-
List of fields to be included in the Fielddata statistics.
94+
[[index-stats-api-multiple-ex]]
95+
===== Get statistics for multiple indices
7396

97+
[source,js]
98+
--------------------------------------------------
99+
GET /index1,index2/_stats
100+
--------------------------------------------------
101+
// CONSOLE
102+
// TEST[s/^/PUT index1\nPUT index2\n/]
74103

75-
Here are some samples:
104+
105+
[[index-stats-api-all-ex]]
106+
===== Get statistics for all indices
107+
108+
[source,js]
109+
--------------------------------------------------
110+
GET /_stats
111+
--------------------------------------------------
112+
// CONSOLE
113+
// TEST[setup:twitter]
114+
115+
116+
[[index-stats-api-specific-stats-ex]]
117+
===== Get specific statistics
118+
119+
The following request returns
120+
only the `merge` and `refresh` statistics
121+
for all indices.
76122

77123
[source,js]
78124
--------------------------------------------------
79-
# Get back stats for merge and refresh only for all indices
80125
GET /_stats/merge,refresh
81-
# Get back stats for type1 and type2 documents for the my_index index
82-
GET /my_index/_stats/indexing?types=type1,type2
83-
# Get back just search stats for group1 and group2
84-
GET /_stats/search?groups=group1,group2
85126
--------------------------------------------------
86127
// CONSOLE
87-
// TEST[s/^/PUT my_index\n/]
128+
// TEST[setup:twitter]
129+
88130

89-
The stats returned are aggregated on the index level, with
90-
`primaries` and `total` aggregations, where `primaries` are the values for only the
91-
primary shards, and `total` are the accumulated values for both primary and replica shards.
131+
[[index-stats-api-specific-groups-ex]]
132+
===== Get statistics for specific search groups
92133

93-
In order to get back shard level stats, set the `level` parameter to `shards`.
134+
The following request returns
135+
only search statistics
136+
for the `group1` and `group2` search groups.
94137

95-
Note, as shards move around the cluster, their stats will be cleared as
96-
they are created on other nodes. On the other hand, even though a shard
97-
"left" a node, that node will still retain the stats that shard
98-
contributed to.
138+
[source,js]
139+
--------------------------------------------------
140+
GET /_stats/search?groups=group1,group2
141+
--------------------------------------------------
142+
// CONSOLE
143+
// TEST[setup:twitter]

0 commit comments

Comments
 (0)