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

Update docs for cluster API #30468

Merged
merged 13 commits into from
Aug 20, 2018
Merged

Update docs for cluster API #30468

Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
165eaf8
Update docs for cluster API
PnPie May 8, 2018
5b4c070
Update according to comments
PnPie May 10, 2018
4344a88
small format change
PnPie May 10, 2018
1ebb53e
still some changes
PnPie May 11, 2018
ff337e9
Merge branch 'master' into 2018-06-08-node-filter-docs
DaveCTurner Jun 8, 2018
86c08f0
Some rewording, and add a note about filters in cluster stats
DaveCTurner Jun 8, 2018
4a63d4a
Merge branch 'master' into update_cluster_api_docs
DaveCTurner Jun 14, 2018
e02ec75
Clarify that both attribute names and values can be patterns
DaveCTurner Jun 14, 2018
19c6cb6
Merge branch 'master' into update_cluster_api_docs
DaveCTurner Jul 2, 2018
dc180f9
Fix regression introduced in merge
DaveCTurner Jul 2, 2018
779e281
Fix regression introduced in merge
DaveCTurner Jul 2, 2018
c11a1ba
Merge branch 'master' into update_cluster_api_docs
DaveCTurner Aug 18, 2018
ae3b2ed
Spell out that wildcards are optional
DaveCTurner Aug 20, 2018
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
52 changes: 41 additions & 11 deletions docs/reference/cluster.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,53 @@
["float",id="cluster-nodes"]
== Node specification

Most cluster level APIs allow to specify which nodes to execute on (for
example, getting the node stats for a node). Nodes can be identified in
the APIs either using their internal node id, the node name, address,
custom attributes, or just the `_local` node receiving the request. For
example, here are some sample executions of nodes info:
Most cluster level APIs allow to specify nodes with `node filters`, these filters
limit the results to selected nodes for corresponding APIs. (For example, you can
find it in APIs like `Cluster State`, `Task Management` and all the Nodes API like
`Nodes States`, `Nodes Info` etc.)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that most cluster-level APIs allow us to specify a set of nodes - by my reckoning it's these:

  • Cluster Stats (via the (undocumented?) ?nodeId= parameter - could also do with fixing)
  • Nodes Stats
  • Nodes Info
  • Nodes Feature Usage
  • Task Management API
  • Nodes hot_threads

There are 13 subheadings in this section, and 6/13 is less than half. (I haven't dug through the code to confirm this so my numbers could be off). In any case it might not be more than half in future, so I think I'd prefer "some" to "most".

Also the things in backticks in this paragraph are not code so I don't think they should be formatted like this. The ones that refer to other pages would be better as links, and node filters is introducing a piece of terminology which we seem either to put in italics or else "in double quotes" depending on taste.

Also also Nodes States should probably be Nodes Stats, and the cluster state API doesn't seem to support a node filter as stated here.

Copy link
Contributor Author

@PnPie PnPie May 11, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that's right, the Cluster Stats API doesn't support node filters, in fact we can only add /nodes to filter the nodes part of the response but no further filtering for that.


Node filters can be one or a list filters which is comma-seperated, each filter can be:

* `_local`
* `_master`
* `_all`
* a node id
* a node name, node address or node hostname (could be a pattern matched using `*` wildcard)
* `[master|data|ingest|coordinating_only]:[true|false]` <1> <2>
* custom `attr:value` (need to be set in configuration file and could be a pattern matched using `*` wildcard) <3>

IMPORTANT: node filters run in order in case of multiple, this is important when you use the exclusion case,
for example `/_all,master:false` means all the nodes exclude master-eligible, but `/master:false,_all` means
all the nodes as you exclude the master-eligible nodes firstly and then add all nodes in.

[NOTE]
===============================================
<1> pay attention that `master` means master-eligible nodes, not the current master which is represented by `_master`.
<2> `false` means exclude the specified type of nodes.
<3> the custom `attr:value` should be defined in configuration file.
===============================================

Here are some node filters examples:

[source,js]
--------------------------------------------------
# Local
# Local node
GET /_nodes/_local
# Address
GET /_nodes/10.0.0.3,10.0.0.4
GET /_nodes/10.0.0.*
# Names
# Master node
GET /_nodes/_master
# All nodes
GET /_nodes/_all
# Using node name
GET /_nodes/node_name_goes_here
GET /_nodes/node_name_goes_*
# Attributes (set something like node.attr.rack: 2 in the config)
# Using address
GET /_nodes/10.0.0.3,10.0.0.4
GET /_nodes/10.0.0.*
# Using built-in `attr:value`
GET /_nodes/_all,master:false
GET /_nodes/data:true,ingest:true
GET /_nodes/coordinating_only:true
# Using custom `attr:value` (set something like `node.attr.rack: 2` in configuration file)
GET /_nodes/rack:2
GET /_nodes/ra*:2
GET /_nodes/ra*:2*
Expand Down