honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/cat/shards.asciidoc

143 lines
5.4 KiB
Plaintext
Raw Normal View History

First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[cat-shards]]
[DOCS] Renamed the "cat" chapters to be more searchable
2014-05-16 15:43:35 -04:00
== cat shards
First pass at cat docs.
2013-11-14 20:14:39 -05:00
The `shards` command is the detailed view of what nodes contain which
shards. It will tell you if it's a primary or replica, the number of
docs, the bytes it takes on disk, and the node where it's located.
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
Here we see a single index, with one primary shard and no replicas:
[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[setup:twitter]
This will return
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
---------------------------------------------------------------------------
// TESTRESPONSE[s/3014/\\d+/]
Doc test: use propery regex for file size The _cat/shards docs asserted that one of the columns looked like a propery byte size but used a regex like `\d+\.\d+.*` which doesn't match `0b` which is a possible value. Instead this uses `\d(\.\d+)?[kmg]?b`.
2017-05-01 15:31:02 -04:00
// TESTRESPONSE[s/31.1mb/\\d+(\.\\d+)?[kmg]?b/]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
// TESTRESPONSE[s/192.168.56.10/.*/]
// TESTRESPONSE[s/H5dfFeA/node-0/ _cat]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
[float]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[index-pattern]]
=== Index pattern
If you have many shards, you may wish to limit which indices show up
in the output. You can always do this with `grep`, but you can save
some bandwidth by supplying an index pattern to the end.
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
[source,js]
---------------------------------------------------------------------------
GET _cat/shards/twitt*
---------------------------------------------------------------------------
// CONSOLE
// TEST[setup:twitter]
Which will return the following
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
---------------------------------------------------------------------------
// TESTRESPONSE[s/3014/\\d+/]
Doc test: use propery regex for file size The _cat/shards docs asserted that one of the columns looked like a propery byte size but used a regex like `\d+\.\d+.*` which doesn't match `0b` which is a possible value. Instead this uses `\d(\.\d+)?[kmg]?b`.
2017-05-01 15:31:02 -04:00
// TESTRESPONSE[s/31.1mb/\\d+(\.\\d+)?[kmg]?b/]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
// TESTRESPONSE[s/192.168.56.10/.*/]
// TESTRESPONSE[s/H5dfFeA/node-0/ _cat]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
[float]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[relocation]]
=== Relocation
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
Let's say you've checked your health and you see a relocating
First pass at cat docs.
2013-11-14 20:14:39 -05:00
shards. Where are they from and where are they going?
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:for now, relocation cannot be recreated]
A relocating shard will be shown as follows
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
---------------------------------------------------------------------------
twitter 0 p RELOCATING 3014 31.1mb 192.168.56.10 H5dfFeA -> -> 192.168.56.30 bGG90GE
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
[float]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
[[states]]
=== Shard states
Before a shard can be used, it goes through an `INITIALIZING` state.
`shards` can show you which ones.
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:there is no guarantee to test for shards in initializing state]
Fix typo in shards.asciidoc (#25143)
2017-06-09 06:43:44 -04:00
You can get the initializing state in the response like this
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
twitter 0 r INITIALIZING 0 14.3mb 192.168.56.30 bGG90GE
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]
First pass at cat docs.
2013-11-14 20:14:39 -05:00
If a shard cannot be assigned, for example you've overallocated the
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
number of replicas for the number of nodes in the cluster, the shard
will remain `UNASSIGNED` with the <<reason-unassigned,reason code>> `ALLOCATION_FAILED`.
First pass at cat docs.
2013-11-14 20:14:39 -05:00
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
You can use the shards API to find out that reason.
[source,js]
---------------------------------------------------------------------------
GET _cat/shards?h=index,shard,prirep,state,unassigned.reason
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:for now]
The reason for an unassigned shard will be listed as the last field
Enforce that responses in docs are valid json (#26249) All of the snippets in our docs marked with `// TESTRESPONSE` are checked against the response from Elasticsearch but, due to the way they are implemented they are actually parsed as YAML instead of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately that means that invalid JSON has snuck into the exmples! This adds a step during the build to parse them as JSON and fail the build if they don't parse. But no! It isn't quite that simple. The displayed text of some of these responses looks like: ``` { ... "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` Note the `...` which isn't valid json but we like it anyway and want it in the output. We use substitution rules to convert the `...` into the response we expect. That yields a response that looks like: ``` { "took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits, "aggregations": { "range": { "buckets": [ { "to": 1.4436576E12, "to_as_string": "10-2015", "doc_count": 7, "key": "*-10-2015" }, { "from": 1.4436576E12, "from_as_string": "10-2015", "doc_count": 0, "key": "10-2015-*" } ] } } } ``` That is what the tests consume but it isn't valid JSON! Oh no! We don't want to go update all the substitution rules because that'd be huge and, ultimately, wouldn't buy much. So we quote the `$body.took` bits before parsing the JSON. Note the responses that we use for the `_cat` APIs are all converted into regexes and there is no expectation that they are valid JSON. Closes #26233
2017-08-17 09:02:10 -04:00
[source,txt]
Documentation: Consoleify cat shards/recovery API docs (#23116) Relates #23001
2017-02-22 03:18:10 -05:00
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
twitter 0 r STARTED 3014 31.1mb 192.168.56.30 bGG90GE
twitter 0 r STARTED 3014 31.1mb 192.168.56.20 I8hydUG
twitter 0 r UNASSIGNED ALLOCATION_FAILED
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
[float]
[[reason-unassigned]]
=== Reasons for unassigned shard
[DOCS] Fixed various typos in the 'cat APIs' section (#23216)
2017-02-16 14:41:42 -05:00
These are the possible reasons for a shard to be in a unassigned state:
Docs explanation for unassigned shard reason codes. Fixes #14001 Closes #15912
2015-12-16 20:55:53 -05:00
[horizontal]
`INDEX_CREATED`:: Unassigned as a result of an API creation of an index.
`CLUSTER_RECOVERED`:: Unassigned as a result of a full cluster recovery.
`INDEX_REOPENED`:: Unassigned as a result of opening a closed index.
`DANGLING_INDEX_IMPORTED`:: Unassigned as a result of importing a dangling index.
`NEW_INDEX_RESTORED`:: Unassigned as a result of restoring into a new index.
`EXISTING_INDEX_RESTORED`:: Unassigned as a result of restoring into a closed index.
`REPLICA_ADDED`:: Unassigned as a result of explicit addition of a replica.
`ALLOCATION_FAILED`:: Unassigned as a result of a failed allocation of the shard.
`NODE_LEFT`:: Unassigned as a result of the node hosting it leaving the cluster.
`REROUTE_CANCELLED`:: Unassigned as a result of explicit cancel reroute command.
`REINITIALIZED`:: When a shard moves from started back to initializing, for example, with shadow replicas.
`REALLOCATED_REPLICA`:: A better replica location is identified and causes the existing replica allocation to be cancelled.