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

134 lines
4.7 KiB
Plaintext
Raw Normal View History

Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[[cluster-health]]
== Cluster Health
The cluster health API allows to get a very simple status on the health
Fix health docs test It failed inconsistently when there were pending tasks.
2016-07-16 07:13:29 -04:00
of the cluster. For example, on a quiet single node cluster with a single index
Default to one shard (#30539) This commit changes the default out-of-the-box configuration for the number of shards from five to one. We think this will help address a common problem of oversharding. For users with time-based indices that need a different default, this can be managed with index templates. For users with non-time-based indices that find they need to re-shard with the split API in place they no longer need to resort only to reindexing. Since this has the impact of changing the default number of shards used in REST tests, we want to ensure that we still have coverage for issues that could arise from multiple shards. As such, we randomize (rarely) the default number of shards in REST tests to two. This is managed via a global index template. However, some tests check the templates that are in the cluster state during the test. Since this template is randomly there, we need a way for tests to skip adding the template used to set the number of shards to two. For this we add the default_shards feature skip. To avoid having to write our docs in a complicated way because sometimes they might be behind one shard, and sometimes they might be behind two shards we apply the default_shards feature skip to all docs tests. That is, these tests will always run with the default number of shards (one).
2018-05-14 12:22:35 -04:00
with one shard and one replica, this:
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[source,js]
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
GET _cluster/health
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT test1\n/]
Returns this:
Remove most of the need for `// NOTCONSOLE` and be much more stingy about what we consider a console candidate. * Add `// CONSOLE` to check-running * Fix version in some snippets * Mark groovy snippets as groovy * Fix versions in plugins * Fix language marker errors * Fix language parsing in snippets This adds support for snippets who's language is written like `[source, txt]` and `["source","js",subs="attributes,callouts"]`. This also makes language required for snippets which is nice because then we can be sure we can grep for snippets in a particular language.
2016-08-29 17:33:25 -04:00
[source,js]
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
--------------------------------------------------
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
{
"cluster_name" : "testcluster",
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
"status" : "yellow",
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
"timed_out" : false,
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
Default to one shard (#30539) This commit changes the default out-of-the-box configuration for the number of shards from five to one. We think this will help address a common problem of oversharding. For users with time-based indices that need a different default, this can be managed with index templates. For users with non-time-based indices that find they need to re-shard with the split API in place they no longer need to resort only to reindexing. Since this has the impact of changing the default number of shards used in REST tests, we want to ensure that we still have coverage for issues that could arise from multiple shards. As such, we randomize (rarely) the default number of shards in REST tests to two. This is managed via a global index template. However, some tests check the templates that are in the cluster state during the test. Since this template is randomly there, we need a way for tests to skip adding the template used to set the number of shards to two. For this we add the default_shards feature skip. To avoid having to write our docs in a complicated way because sometimes they might be behind one shard, and sometimes they might be behind two shards we apply the default_shards feature skip to all docs tests. That is, these tests will always run with the default number of shards (one).
2018-05-14 12:22:35 -04:00
"active_primary_shards" : 1,
"active_shards" : 1,
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
"relocating_shards" : 0,
"initializing_shards" : 0,
Default to one shard (#30539) This commit changes the default out-of-the-box configuration for the number of shards from five to one. We think this will help address a common problem of oversharding. For users with time-based indices that need a different default, this can be managed with index templates. For users with non-time-based indices that find they need to re-shard with the split API in place they no longer need to resort only to reindexing. Since this has the impact of changing the default number of shards used in REST tests, we want to ensure that we still have coverage for issues that could arise from multiple shards. As such, we randomize (rarely) the default number of shards in REST tests to two. This is managed via a global index template. However, some tests check the templates that are in the cluster state during the test. Since this template is randomly there, we need a way for tests to skip adding the template used to set the number of shards to two. For this we add the default_shards feature skip. To avoid having to write our docs in a complicated way because sometimes they might be behind one shard, and sometimes they might be behind two shards we apply the default_shards feature skip to all docs tests. That is, these tests will always run with the default number of shards (one).
2018-05-14 12:22:35 -04:00
"unassigned_shards" : 1,
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
"active_shards_percent_as_number": 50.0
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
}
--------------------------------------------------
[TEST] Fix incorrect test cluster name in cluster health doc tests
2017-02-22 19:17:34 -05:00
// TESTRESPONSE[s/testcluster/docs_integTestCluster/]
Fix health docs test It failed inconsistently when there were pending tasks.
2016-07-16 07:13:29 -04:00
// TESTRESPONSE[s/"number_of_pending_tasks" : 0,/"number_of_pending_tasks" : $body.number_of_pending_tasks,/]
// TESTRESPONSE[s/"task_max_waiting_in_queue_millis": 0/"task_max_waiting_in_queue_millis": $body.task_max_waiting_in_queue_millis/]
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
The API can also be executed against one or more indices to get just the
specified indices health:
[source,js]
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
GET /_cluster/health/test1,test2
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
// CONSOLE
// TEST[s/^/PUT test1\nPUT test2\n/]
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
The cluster health status is: `green`, `yellow` or `red`. On the shard
level, a `red` status indicates that the specific shard is not allocated
in the cluster, `yellow` means that the primary shard is allocated but
replicas are not, and `green` means that all shards are allocated. The
index level status is controlled by the worst shard status. The cluster
status is controlled by the worst index status.
One of the main benefits of the API is the ability to wait until the
cluster reaches a certain high water-mark health level. For example, the
Clean up wording to reduce confusion The description of the timeout parameter was worded misleadingly; it implied that the API would wait until the cluster reached the desired level and then stayed at that level for the timeout. I've tweaked the sentence to remove the risk of confusion.
2013-10-21 07:37:50 -04:00
following will wait for 50 seconds for the cluster to reach the `yellow`
level (if it reaches the `green` or `yellow` status before 50 seconds elapse,
it will return at that point):
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[source,js]
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
GET /_cluster/health?wait_for_status=yellow&timeout=50s
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
// CONSOLE
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[float]
Add more anchor links to documentation Related to #3679
2013-09-25 12:17:40 -04:00
[[request-params]]
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
=== Request Parameters
The cluster health API accepts the following request parameters:
`level`::
Can be one of `cluster`, `indices` or `shards`. Controls the
details level of the health information returned. Defaults to `cluster`.
`wait_for_status`::
One of `green`, `yellow` or `red`. Will wait (until
the timeout provided) until the status of the cluster changes to the one
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
provided or better, i.e. `green` > `yellow` > `red`. By default, will not
Docs: Updated cluster health docs
2014-06-20 12:04:51 -04:00
wait for any status.
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
Parameter improvements to Cluster Health API wait for shards (#20223) * Params improvements to Cluster Health API wait for shards Previously, the cluster health API used a strictly numeric value for `wait_for_active_shards`. However, with the introduction of ActiveShardCount and the removal of write consistency level for replication operations, `wait_for_active_shards` is used for write operations to represent values for ActiveShardCount. This commit moves the cluster health API's usage of `wait_for_active_shards` to be consistent with its usage in the write operation APIs. This commit also changes `wait_for_relocating_shards` from a numeric value to a simple boolean value `wait_for_no_relocating_shards` to set whether the cluster health operation should wait for all relocating shards to complete relocation. * Addresses code review comments * Don't be lenient if `wait_for_relocating_shards` is set
2016-08-31 11:58:19 -04:00
`wait_for_no_relocating_shards`::
A boolean value which controls whether to wait (until the timeout provided)
for the cluster to have no shard relocations. Defaults to false, which means
it will not wait for relocating shards.
Docs: Documented delayed allocation settings Relates to: #11712
2015-06-30 07:53:04 -04:00
Add wait_for_no_initializing_shards to cluster health API (#27489) This adds a new option to the cluster health request allowing to wait until there is no initializing shards. Closes #25623
2017-11-23 15:09:58 -05:00
`wait_for_no_initializing_shards`::
A boolean value which controls whether to wait (until the timeout provided)
for the cluster to have no shard initializations. Defaults to false, which means
it will not wait for initializing shards.
[DOCS] add wait_for_active_shards option to health.asciidoc
2015-04-02 03:14:20 -04:00
`wait_for_active_shards`::
Parameter improvements to Cluster Health API wait for shards (#20223) * Params improvements to Cluster Health API wait for shards Previously, the cluster health API used a strictly numeric value for `wait_for_active_shards`. However, with the introduction of ActiveShardCount and the removal of write consistency level for replication operations, `wait_for_active_shards` is used for write operations to represent values for ActiveShardCount. This commit moves the cluster health API's usage of `wait_for_active_shards` to be consistent with its usage in the write operation APIs. This commit also changes `wait_for_relocating_shards` from a numeric value to a simple boolean value `wait_for_no_relocating_shards` to set whether the cluster health operation should wait for all relocating shards to complete relocation. * Addresses code review comments * Don't be lenient if `wait_for_relocating_shards` is set
2016-08-31 11:58:19 -04:00
A number controlling to how many active shards to wait for, `all` to wait
for all shards in the cluster to be active, or `0` to not wait. Defaults to `0`.
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
`wait_for_nodes`::
The request waits until the specified number `N` of
nodes is available. It also accepts `>=N`, `<=N`, `>N` and `<N`.
Alternatively, it is possible to use `ge(N)`, `le(N)`, `gt(N)` and
`lt(N)` notation.
REST high-level client: add Cluster Health API (#29331) Relates to #27205
2018-06-12 07:34:06 -04:00
`wait_for_events`::
Can be one of `immediate`, `urgent`, `high`, `normal`, `low`, `languid`.
Wait until all currently queued events with the given priority are processed.
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
`timeout`::
A time based parameter controlling how long to wait if one of
the wait_for_XXX are provided. Defaults to `30s`.
REST high-level client: add Cluster Health API (#29331) Relates to #27205
2018-06-12 07:34:06 -04:00
`master_timeout`::
A time based parameter controlling how long to wait if the master has not been
discovered yet or disconnected.
If not provided, uses the same value as `timeout`.
Added desc for parameter <local>
2015-12-11 19:26:33 -05:00
`local`::
If `true` returns the local node information and does not provide
the state from master node. Default: `false`.
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
The following is an example of getting the cluster health at the
`shards` level:
[source,js]
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
GET /_cluster/health/twitter?level=shards
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
--------------------------------------------------
Convert snippets in health docs to CONSOLE This should make them easier to read and adds them to the test suite I changed the example from a two node cluster to a single node cluster because that is what we have running in the integration tests. It is also what a user just starting out is likely to see so I think that is ok.
2016-07-15 16:28:45 -04:00
// CONSOLE
// TEST[setup:twitter]