Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Reformat index stats API docs #46322

Merged
merged 6 commits into from
Sep 5, 2019
Merged

[DOCS] Reformat index stats API docs #46322

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c6d1da4
[DOCS] Reformat index stats API docs
jrodewig Sep 4, 2019
f3f46c2
change // CONSOLE comments to [source,console]
jrodewig Sep 4, 2019
da54465
Update docs/reference/rest-api/common-parms.asciidoc
jrodewig Sep 5, 2019
2e4d91e
fix copy/paste error
jrodewig Sep 5, 2019
730f68f
fix wording
jrodewig Sep 5, 2019
80cc85e
Merge branch 'master' into index-stats-reformat
jrodewig Sep 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 6 additions & 19 deletions docs/reference/cluster/nodes-stats.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,36 +113,23 @@ 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
`indexing` index metric.

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]]
Expand Down
176 changes: 108 additions & 68 deletions docs/reference/indices/stats.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
Loading