Cluster API详解
Cluster API主要是用来查看或更改集群相关的信息或设置。 其中，一些集群级API可以在节点的子集上操作，这些节点可以通过节点过滤器指定。例如，任务管理、节点统计信息和节点信息API可以从一组经过过滤的节点而不是从所有节点报告结果。
1、节点过滤
节点过滤器是用逗号分隔的单个过滤器列表形式，每个过滤器都 会添加或删除所选子集中的节点。
| 过滤器 | 描述 |
|---|---|
| _all | 将所有节点添加到子集中 |
| _local | 将本地节点添加到子集中 |
| 节点的ID或名称 | 把指定ID或名称的节点添加到子集中 |
| IP或主机名 | 把指定IP或主机名称的节点添加到子集中 |
| * | 节点名称、ID、IP、主机名称可以包括通配符 |
| master:true | 把主节点添加到子集中 |
| data:true | 把数据节点添加到子集中 |
| ingest:true | 把索引预处理节点添加到子集中 |
| coordinating_only:true | 把协调节点添加到子集中 |
| master:false | 从子集中剔除主节点 |
| data:false | 从子集中剔除数据主节点 |
| ingest:false | 从子集中剔除索引预处理节点 |
| coordinating_only:false | 从子集中剔除协调节点 |
| attrname：attrValue | 将具有名称和值与相应模式匹配的自定义节点属性的所有节点添加到子集。通过设置node.attr.attrname：attrValue形式的配置文件中的属性来配置自定义节点属性。 |
示例：
//默认选取所有节点
GET /_nodes
//显示所有节点
GET /_nodes/_all
//只选取本地节点
GET /_nodes/_local
//只选取主节点
GET /_nodes/_master
//通过指定的名称选取节点，可以包含通配符*
GET /_nodes/node_name_goes_here
GET /_nodes/node_name_goes_*
//通过IP地址选取节点，可以包含通配符
GET /_nodes/10.0.0.3,10.0.0.4
GET /_nodes/10.0.0.*
//根据节点类型选择
GET /_nodes/_all,master:false
GET /_nodes/data:true,ingest:true
GET /_nodes/coordinating_only:true
GET /_nodes/master:true,voting_only:false
//根据自定义属性选择节点
GET /_nodes/rack:2
GET /_nodes/ra*:2
GET /_nodes/ra*:2*
2、节点类型
在Elasticsearch集群中，可以设置候选主节点、数据节点、索 引预处理节点、协调节点四种类的节点，各种类型的节点在集群中扮 演着不同的角色。
2.1、主节点
主节点是从候选主节点列表中选出的。主节点的主要职责是和集 群操作相关的内容，如创建或删除索引，跟踪哪些节点是群集的一部 分，并决定哪些分片分配给相关的节点。稳定的主节点对集群的健康 是非常重要的。索引数据和搜索查询等操作会占用大量的CPU、内 存、IO资源，为了确保一个集群的稳定，分离主节点和数据节点是一 个比较好的选择。
2.2、候选主节点
默认情况下集群中的任何节点都是候选主节点。此类型节点可以 在elasticsearch.yml中显式配置和禁止。
配置节点为候选主节点（默认值）：
node.master:true
禁止节点为候选主节点：
node.master:false
2.3、数据节点
数据节点用来存储索引数据，主要对文档进行增删改查操作，聚 合操作等。数据节点对CPU、内存，IO要求较高，在优化的时候需要 监控数据节点的状态，当资源不够的时候，需要在集群中添加新的节 点。此类型节点可以在elasticsearch.yml中显式配置和禁止。
配置节点为数据节点（默认值）：
node.data:true
禁止节点为数据节点：
node.data:false
2.4、索引预处理节点
这种类型的节点用来预处理数据。在索引前预处理文档，拦截 bulk、index请求，然后再回传给bulk、index API。用户可以自定 义管道，指定一系列的预处理器。此类型节点可以在 elasticsearch.yml中显式配置和禁止。
配置节点为索引预处理节点:
node.ingest:true
禁止节点为索引预处理节点（默认值）：
node.ingest:false
2.5、协调节点
这种类型的节点既不会成为主节点，也不会存储数据，这个节点 只负责接收和转发请求，针对海量请求的时候可以进行负载均衡。此 类型节点可以在elasticsearch.yml中显式配置和禁止。
配置节点为协调节点:
coordinating_only:true
禁止节点为协调节点(默认值):
coordinating_only:false
2.6、分配各种类型节点的规则
如何分配各种类型的节点，更多的是结合资源、并发量、数据量 等实际因素。在一个生产集群中，对这些节点的职责进行划分是十分 必要的。以下是一些经验性的规则。
- 建议集群中设置3个以上的节点作为候选主节点，这些节点 只负责成为主节点，维护整个集群的状态，不接受请求，也 不存储数据。配置如下:
node.master:true
node.data:false
node.ingest:false
- 根据数据量设置一批数据节点，这些节点只负责存储数据， 集群中这类节点的压力是最大的。配置如下:
node.master:false
node.data:true
node.ingest:false
- 在集群中建议设置一批协调节点，这些节点只负责处理用户 请求，实现请求转发，负载均衡等功能。配置如下:
node.master:false
node.data:false
node.ingest:false
#也可以这样配置
coordinating_only:false
3、查看集群健康(health)
查看集群健康状况:
//语法
GET _cluster/health/<index>
示例：
GET _cluster/health
返回：
{
"cluster_name" : "elasticsearch",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 49,
"active_shards" : 49,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 37,
"delayed_unassigned_shards" : 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch" : 0,
"task_max_waiting_in_queue_millis" : 0,
"active_shards_percent_as_number" : 56.97674418604651
}
-
cluster_name：集群名称 -
status：集群状态green：所有分片都已分配。yellow：所有主分片已分配，但有未分配的一个或多个副本分片。如果群集中的某个节点出现故障，则在修复该节点之前，某些数据可能不可用。red：一个或多个主分片未分配，因此某些数据不可用。在分配主分片时，这可能会在集群启动期间短暂出现。
-
timed_out：(布尔值)如果为FALSE，则在超时参数指定的时间段(默认为30秒)内返回响应。 -
number_of_nodes：节点数量 -
number_of_data_nodes：作为专用数据节点的节点数。 -
active_primary_shards：活跃的主分片数。 -
active_shards：活跃的主分片和副本分片的总数。 -
relocating_shards：正在迁移中的分片数。 -
initializing_shards：正在初始化的分片数。 -
unassigned_shards：未分配的分片数。 -
delayed_unassigned_shards：因超时设置而延迟分配的分片数量。 -
number_of_pending_tasks：尚未执行的群集级更改的数量。 -
number_of_in_flight_fetch：未完成的提取数。 -
task_max_waiting_in_queue_millis：自最早启动的任务等待执行以来的时间，以毫秒表示。 -
active_shards_percent_as_number：集群中活动分片的比率，以百分比表示。
4、查看集群状态(state)
集群状态API允许访问表示整个集群状态的元数据。这包括以下信息。
- 群集中的节点集。
- 所有群集级设置。
- 有关集群中的索引的信息，包括它们的映射和设置。
- 群集中所有碎片的位置。
//语法
GET /_cluster/state/<metrics>/<index>
路径参数：
-
<metrics>：(可选，字符串)以下选项的逗号分隔列表_all：blocks：master_node：metadata：nodes：routing_nodes：routing_table：version：
-
<index>：(可选，字符串)用于限制请求的索引名的逗号分隔列表或通配符表达式。
示例：
GET /_cluster/state/metadata,routing_table/bank
GET /_cluster/state/_all/foo,bar
GET /_cluster/state/blocks
返回：
{
"cluster_name" : "elasticsearch",
"cluster_uuid" : "ACAp2pYNQvaGyKKEzw3SWg",
"blocks" : {
"indices" : {
"my_source_index" : {
"8" : {
"description" : "index write (api)",
"retryable" : false,
"levels" : [
"write"
]
}
}
}
}
}
5、查看集群统计信息(stats)
Cluster Stats（集群统计信息）API 可以获取集范围内的统计信息。该 API 返回基本的索引 metric（度量）（分片数量，存储大小，内存使用）和关于当前集群（编号，角色，系统，jvm 版本，内存使用，cpu 和安装的插件）中节点的信息。
//语法
GET /_cluster/stats
GET /_cluster/stats/nodes/<node_filter>
示例：
GET /_cluster/stats?human&pretty
返回：
{
"_nodes" : { //节点指标
"total" : 1, //"本次请求选择的节点总数。"
"successful" : 1, //成功响应请求的节点数。
"failed" : 0 //拒绝请求或未能响应的节点数。如果此值不为0，则响应中包含拒绝或失败的原因。
},
"cluster_name" : "elasticsearch",//集群名称
"cluster_uuid" : "ACAp2pYNQvaGyKKEzw3SWg",//集群id
"timestamp" : 1697689481543,//上次刷新群集统计信息的Unix时间戳，以毫秒为单位。
"status" : "yellow", //集群状态
"indices" : { //索引指标
"count" : 50,//索引总数
"shards" : { //分片的统计信息。
"total" : 50,//分片总数
"primaries" : 50,//主分片数
"replication" : 0.0,//副本分片与主分片的比率
"index" : {
"shards" : {
"min" : 1,//一个索引允许的最小分片数量。
"max" : 1,//一个索引允许的最大分片数量
"avg" : 1.0//索引的平均分片数量。
},
"primaries" : {
"min" : 1,//一个索引允许的最小主分片数。
"max" : 1,//一个索引允许的最大主分片数。
"avg" : 1.0//索引的平均主分片数量。
},
"replication" : {
"min" : 0.0,//一个索引允许的最小副本因子，即最小允许几个副本。
"max" : 0.0,//一个索引允许的最大副本因子，即最大允许几个副本。
"avg" : 0.0//索引的平均副本因子，即平均有几个副本。
}
}
},
"docs" : {//文档指标
"count" : 61552,//主分片中未删除的文档数量。
"deleted" : 203//主分片中已删除的文档数量。
},
"store" : {//存储指标
"size" : "45mb",//分片占用总大小，单位字节。
"size_in_bytes" : 47285470,//以字节为单位的预测，即由于正在进行的对等恢复、恢复快照和类似活动，分片存储最终会增长多少，单位是字节。
"total_data_set_size" : "45mb",
"total_data_set_size_in_bytes" : 47285470,
"reserved" : "0b",
"reserved_in_bytes" : 0
},
"fielddata" : {//字段数据指标
"memory_size" : "288b",//字段占用总大小
"memory_size_in_bytes" : 288,//字段数据缓存总大小，单位字节。
"evictions" : 0//驱逐缓存的大小，当超过堆内存阈值为了安全保护时会被驱逐，查询抛出Data too large异常。
},
"query_cache" : {//查询缓存指标 查询缓存用于缓存查询结果，默认为堆内存的10%，可以通过参数indices.queries.cache.size。调优该参数可以提高命中率，提高查询性能。
"memory_size" : "0b",//查询缓存占用总大小
"memory_size_in_bytes" : 0,//查询缓存总大小。
"total_count" : 0,//查询缓存中命中和未命中的总数。
"hit_count" : 0,//查询缓存中总的命中数量。
"miss_count" : 0,//查询缓存中总的未命中数量。
"cache_size" : 0,//查询缓存中当前总的条目总数。
"cache_count" : 0,//查询缓存中总的条目数包含被驱逐的，是cache_size与evictions之和
"evictions" : 0//查询缓存中被驱逐的条目总数。
},
"completion" : {//completion缓存指标 Linux内核中用于唤醒等待队列中睡眠线程，等待队列占用的缓存大小。
"size" : "0b",//complete缓存大小
"size_in_bytes" : 0//complete缓存使用大小。
},
"segments" : {//segments指标
"count" : 84,//segments的数量总数。
"memory" : "334.8kb",
"memory_in_bytes" : 342912,//segments使用的缓存总和。
"terms_memory" : "213.5kb",
"terms_memory_in_bytes" : 218624,//terms query使用的缓存大小。
"stored_fields_memory" : "40.6kb",
"stored_fields_memory_in_bytes" : 41632,//fields使用缓存大小。
"term_vectors_memory" : "488b",
"term_vectors_memory_in_bytes" : 488,//Term Vectors（词条向量）使用缓存大小。
"norms_memory" : "16.9kb",
"norms_memory_in_bytes" : 17344,//norms（标准信息）使用的缓存大小。
"points_memory" : "0b",
"points_memory_in_bytes" : 0,//points使用的缓存大小。
"doc_values_memory" : "63.3kb",
"doc_values_memory_in_bytes" : 64824,//doc values占用缓存大小。
"index_writer_memory" : "292.2kb",
"index_writer_memory_in_bytes" : 299312,//index writer占用缓存大小。
"version_map_memory" : "190b",
"version_map_memory_in_bytes" : 190,//version maps（描述document、fields包含的内容）占用的缓存大小。
"fixed_bit_set" : "968b",
"fixed_bit_set_memory_in_bytes" : 968,//BitSet（带标状态的数组）占用缓存的大小。
"max_unsafe_auto_id_timestamp" : 1697689285027,//documents自动生成IDs最新时间戳。
"file_sizes" : { }
},
"mappings" : {//mappings指标
"field_types" : [
{
"name" : "alias",//字段数据类型。
"count" : 1,//该字段数据类型在集群中的数量。
"index_count" : 1,//使用该字段类型的索引数量。
"script_count" : 0
},
{
"name" : "boolean",
"count" : 3,
"index_count" : 2,
"script_count" : 0
},
{
"name" : "constant_keyword",
"count" : 3,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "date",
"count" : 25,
"index_count" : 10,
"script_count" : 0
},
{
"name" : "date_range",
"count" : 1,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "double",
"count" : 1,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "float",
"count" : 13,
"index_count" : 6,
"script_count" : 0
},
{
"name" : "geo_point",
"count" : 6,
"index_count" : 5,
"script_count" : 0
},
{
"name" : "geo_shape",
"count" : 1,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "half_float",
"count" : 12,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "integer",
"count" : 8,
"index_count" : 4,
"script_count" : 0
},
{
"name" : "ip",
"count" : 3,
"index_count" : 2,
"script_count" : 0
},
{
"name" : "ip_range",
"count" : 1,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "join",
"count" : 2,
"index_count" : 2,
"script_count" : 0
},
{
"name" : "keyword",
"count" : 205,
"index_count" : 29,
"script_count" : 0
},
{
"name" : "long",
"count" : 36,
"index_count" : 13,
"script_count" : 0
},
{
"name" : "nested",
"count" : 2,
"index_count" : 2,
"script_count" : 0
},
{
"name" : "object",
"count" : 43,
"index_count" : 9,
"script_count" : 0
},
{
"name" : "percolator",
"count" : 1,
"index_count" : 1,
"script_count" : 0
},
{
"name" : "text",
"count" : 118,
"index_count" : 31,
"script_count" : 0
},
{
"name" : "version",
"count" : 1,
"index_count" : 1,
"script_count" : 0
}
],
"runtime_field_types" : [ ]
},
"analysis" : {//analyzer指标
"char_filter_types" : [ ],
"tokenizer_types" : [ ],
"filter_types" : [ ],
"analyzer_types" : [ ],
"built_in_char_filters" : [ ],
"built_in_tokenizers" : [ ],
"built_in_filters" : [ ],
"built_in_analyzers" : [
{
"name" : "english",
"count" : 1,
"index_count" : 1
},
{
"name" : "ik_max_word",
"count" : 2,
"index_count" : 1
},
{
"name" : "ik_smart",
"count" : 1,
"index_count" : 1
},
{
"name" : "standard",
"count" : 2,
"index_count" : 1
}
]
},
"versions" : [
{
"version" : "7.16.0",
"index_count" : 50,
"primary_shard_count" : 50,
"total_primary_size" : "45mb",
"total_primary_bytes" : 47285470
}
]
},
"nodes" : {//nodes指标
"count" : {
"total" : 1,//总节点数量。
"coordinating_only" : 0,//协作节点（coordinating）的数量。
"data" : 1,//data节点的数量。
"data_cold" : 1,//data冷节点的数量。
"data_content" : 1,
"data_frozen" : 1,
"data_hot" : 1,//data热节点的数量。
"data_warm" : 1,
"ingest" : 1,
"master" : 1,
"ml" : 1,
"remote_cluster_client" : 1,
"transform" : 1,
"voting_only" : 0
},
"versions" : [//使用的elasticsearch版本。
"7.16.0"
],
"os" : {
"available_processors" : 12,//可用的处理器核数。
"allocated_processors" : 12,//已分配的处理器核数。
"names" : [
{
"name" : "Mac OS X",//os.pretty_names
"count" : 1
}
],
"pretty_names" : [
{
"pretty_name" : "Mac OS X",//操作系统名称。
"count" : 1
}
],
"architectures" : [
{
"arch" : "x86_64",//架构
"count" : 1
}
],
"mem" : {
"total" : "16gb",//总的物理内存。
"total_in_bytes" : 17179869184,
"free" : "113mb",//nodes.mem.used_in_bytes
"free_in_bytes" : 118493184,
"used" : "15.8gb",//已使用的物理内存。
"used_in_bytes" : 17061376000,
"free_percent" : 1,//空闲内存占比。
"used_percent" : 99//已使用内存占比。
}
},
"process" : {//处理器指标
"cpu" : {
"percent" : 2//cpu使用的百分比
},
"open_file_descriptors" : {//文件描述符指标
"min" : 594,
"max" : 594,
"avg" : 594
}
},
"jvm" : {//JVM指标
"max_uptime" : "3.5m",//jvm启动了多久。
"max_uptime_in_millis" : 211892,
"versions" : [//jvm启动了多久。
{
"version" : "1.8.0_211",
"vm_name" : "Java HotSpot(TM) 64-Bit Server VM",
"vm_version" : "25.211-b12",
"vm_vendor" : "Oracle Corporation",
"bundled_jdk" : true,
"using_bundled_jdk" : false,
"count" : 1
}
],
"mem" : {
"heap_used" : "249.7mb",//已使用的堆内存。
"heap_used_in_bytes" : 261933304,
"heap_max" : "989.8mb",//最大堆内存。
"heap_max_in_bytes" : 1037959168
},
"threads" : 103
},
"fs" : {//file stores指标
"total" : "465.6gb",//总的磁盘大小。
"total_in_bytes" : 499963174912,
"free" : "48.2gb",//未分配的磁盘空间大小。
"free_in_bytes" : 51839795200,
"available" : "35.3gb",//jvm可用的磁盘空间余量。
"available_in_bytes" : 37933821952
},
"plugins" : [//插件信息
{
"name" : "analysis-ik",
"version" : "7.16.0",
"elasticsearch_version" : "7.16.0",
"java_version" : "1.8",
"description" : "IK Analyzer for Elasticsearch",
"classname" : "org.elasticsearch.plugin.analysis.ik.AnalysisIkPlugin",
"extended_plugins" : [ ],
"has_native_controller" : false,
"licensed" : false,
"type" : "isolated"
}
],
"network_types" : {
"transport_types" : {
"security4" : 1
},
"http_types" : {
"security4" : 1
}
},
"discovery_types" : {
"zen" : 1
},
"packaging_types" : [
{
"flavor" : "default",
"type" : "tar",
"count" : 1
}
],
"ingest" : {
"number_of_pipelines" : 1,
"processor_stats" : {
"gsub" : {
"count" : 0,
"failed" : 0,
"current" : 0,
"time" : "0s",
"time_in_millis" : 0
},
"script" : {
"count" : 0,
"failed" : 0,
"current" : 0,
"time" : "0s",
"time_in_millis" : 0
}
}
}
}
}
}
6、集群设置(setting)
6.1、获取集群设置信息
默认情况下，此API调用仅返回已显式定义的设置，但也可以通过调用INCLUDE_DEFAULTS参数包括默认设置。
//语法
GET /_cluster/settings
示例：
GET /_cluster/settings?include_defaults=true
返回：
{
"persistent" : { },
"transient" : { },
"defaults" : { ... }
}
6.2、更新集群设置信息
//语法
PUT /_cluster/settings
示例：持久更新
PUT /_cluster/settings
{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}
示例：临时更新
PUT /_cluster/settings?flat_settings=true
{
"transient" : {
"indices.recovery.max_bytes_per_sec" : "20mb"
}
}
示例：重置一个设置
PUT /_cluster/settings
{
"transient" : {
"indices.recovery.max_bytes_per_sec" : null
}
}
示例：重置匹配的多个设置
PUT /_cluster/settings
{
"transient" : {
"indices.recovery.*" : null
}
}
7、查看节点信息(_nodes)
//语法
GET /_nodes
GET /_nodes/<node_id>
GET /_nodes/<metric>
GET /_nodes/<node_id>/<metric>
路径参数：
-
<metric>：可选的指标，逗号分隔列表httpingestjvmospluginsprocesssettingsthread_pooltransport
-
<node_id>：(可选，字符串)用于限制返回信息的节点ID或名称的逗号分隔列表。
示例：
//只返回process
GET /_nodes/process
GET /_nodes/_all/process
//只返回nodeId1和nodeId2的jvm和process参数
GET /_nodes/nodeId1,nodeId2/jvm,process
GET /_nodes/nodeId1,nodeId2/info/jvm,process
//返回
GET /_nodes/nodeId1,nodeId2/_all
8、查看节点统计信息(_nodes/stats)
//语法
GET /_nodes/stats
GET /_nodes/<node_id>/stats
GET/_nodes/stats/<metric>
GET/_nodes/<node_id>/stats/<metric>
GET /_nodes/stats/<metric>/<index_metric>
GET /_nodes/<node_id>/stats/<metric>/<index_metric>
路径参数：
-
<metric>：可选的指标，逗号分隔列表httpingestjvmospluginsprocesssettingsthread_pooltransport
-
<index_metric>：可选的索引指标，逗号分隔列表completiondocsfielddataflushgetindexingmergequery_cacherecoveryrefreshrequest_cachesearchsegmentsstoretranslogwarmer
-
<node_id>：(可选，字符串)用于限制返回信息的节点ID或名称的逗号分隔列表。
示例：
GET /_nodes/stats/indices
GET /_nodes/stats/os,process
GET /_nodes/10.0.0.1/stats/process
GET /_nodes/stats/indices/fielddata?fields=field1,field2
GET /_nodes/stats/indices/fielddata?level=indices&fields=field1,field2
GET /_nodes/stats/indices/fielddata?level=shards&fields=field1,field2
GET /_nodes/stats/indices/fielddata?fields=field*
GET /_nodes/stats?groups=_all
GET /_nodes/stats/indices?groups=foo,bar
9、重置路由(reroute)
重置路由是一个高级应用，允许手动更改集群中单个分片的分 配。例如，可以显式地将分片从一个节点移动到另一个节点，可以取 消分配，也可以显式地将未分配的分片分配到特定的节点。
//语法
POST /_cluster/reroute
示例：
POST /_cluster/reroute
{
"commands" : [
{
"move" : {
"index" : "test", "shard" : 0,
"from_node" : "node1", "to_node" : "node2"
}
},
{
"allocate_replica" : {
"index" : "test", "shard" : 1,
"node" : "node3"
}
}
]
}
重要的是要注意，任何重置路由命令执行完成后， Elasticsearch 将 正 常 执 行 重 新 平 衡 ( 受 cluster.routing.rebalance.enable等设置的值影响)，以保持平衡 状态。例如，如果请求的分配将分片从node1移动到node2，那么这 可能会导致分片从node2移动回node1，从而使集群重新均衡。
可以使用cluster.routing.allocation.enable设置为false将集群 设置为禁止分片自动分配。
