基于 Zabbix agent 的 Elasticsearch 集群监控模板:App Elasticsearch Cluster by Zabbix agent 深度解析
基于 Zabbix agent 的 Elasticsearch 集群监控模板:App Elasticsearch Cluster by Zabbix agent 深度解析
导读
App Elasticsearch Cluster by Zabbix agent 是 Zabbix Community Templates 仓库中专门用于监控 Elasticsearch 集群的官方衍生模板(作者 Evren Yurtesen)。它不依赖任何外部脚本,通过 Zabbix agent 内置的 HTTP agent 能力一次性拉取 Elasticsearch 的 REST API(_cluster/health、_cluster/stats、_nodes/stats、_settings),再借助 dependent item 与预处理将 JSON 拆解为数百个可观测指标,同时覆盖集群健康、节点 JVM/线程池/索引延迟、只读索引等关键场景。阅读本文后,你将掌握该模板的采集架构、全部宏参数、监控项与告警设计,并能在 Zabbix 5.0 及更高版本中直接导入使用、按需调参。
本文以仓库中的 5.0 README 为主体,结合同目录下的 模板 XML 导出(以及 5.4、6.0 版本对应的 YAML 导出)进行源码级印证,确保每个结论都有仓库依据。
模板概览与设计原理
该模板是随 Zabbix 5.0 发布的官方 Elasticsearch HTTP 模板的 "Zabbix agent" 版本。核心设计思路:
- 零外部脚本:所有数据均通过 Zabbix agent 内建的
web.page.get键采集,无需在被监控机上部署任何采集脚本; - 单次拉取、多处复用:每个 REST API 端点只被一个 "master item" 拉取一次,其余指标全部由 dependent item 通过 JSONPath 预处理从同一份原始 JSON 中提取,极大降低 API 请求频率;
- 单机与集群通吃:既适用于单节点 standalone 实例,也适用于多节点集群(借助 LLD 逐节点展开监控项);
- 远程与本地皆可:通过
{$ELASTICSEARCH.HOST}宏可让 agent 采集 localhost 上的 Elasticsearch,也可采集网络可达的远端节点(agent 需能访问对应地址与端口)。
模板作者在原 HTTP 版基础上做了两处增强(README 的 Overview 中明确说明):
- 增加只读索引检查:Elasticsearch 在磁盘空间不足(超过 flood stage 水位)时会把索引置为只读,模板通过
_settings接口识别index.blocks.read_only_allow_delete状态并产生高优先级告警; - 增加 cluster_name 采集:将集群名称作为监控项收集。
宏参数配置:连接信息与告警阈值
模板的全部可调参数均以宏形式提供,可在模板级或主机级覆盖。下表完整列出 README 中声明的 12 个宏:
| 宏 | 描述 | 默认值 | 类型 |
|---|---|---|---|
{$ELASTICSEARCH.FETCH_LATENCY.MAX.WARN} |
fetch 延迟告警阈值(毫秒),用于触发器表达式 | 100 |
文本宏 |
{$ELASTICSEARCH.FLUSH_LATENCY.MAX.WARN} |
flush 延迟告警阈值(毫秒) | 100 |
文本宏 |
{$ELASTICSEARCH.HEAP_USED.MAX.CRIT} |
JVM 堆使用率严重告警阈值(百分比) | 95 |
文本宏 |
{$ELASTICSEARCH.HEAP_USED.MAX.WARN} |
JVM 堆使用率警告阈值(百分比) | 85 |
文本宏 |
{$ELASTICSEARCH.HOST} |
Elasticsearch 主机名 | localhost |
文本宏 |
{$ELASTICSEARCH.INDEXING_LATENCY.MAX.WARN} |
索引延迟告警阈值(毫秒) | 100 |
文本宏 |
{$ELASTICSEARCH.PASSWORD} |
Elasticsearch 访问密码 | 空 | 文本宏 |
{$ELASTICSEARCH.PORT} |
Elasticsearch 端口 | 9200 |
文本宏 |
{$ELASTICSEARCH.QUERY_LATENCY.MAX.WARN} |
查询延迟告警阈值(毫秒) | 100 |
文本宏 |
{$ELASTICSEARCH.RESPONSE_TIME.MAX.WARN} |
集群最大响应时间告警阈值(秒) | 10s |
文本宏 |
{$ELASTICSEARCH.SCHEME} |
协议(http/https) | http |
文本宏 |
{$ELASTICSEARCH.USERNAME} |
Elasticsearch 访问用户名 | 空 | 文本宏 |
这些默认值在 5.0 XML 导出的 macros 段 与 6.0 YAML 导出的 macros 段 中与 README 完全一致,可交叉验证。
使用要点:
- 连接类宏:若 Elasticsearch API 不在默认的
localhost:9200,需覆盖{$ELASTICSEARCH.SCHEME}、{$ELASTICSEARCH.HOST}、{$ELASTICSEARCH.PORT};若启用了安全认证(如 X-Pack),在主机级填写{$ELASTICSEARCH.USERNAME}与{$ELASTICSEARCH.PASSWORD}; - 阈值类宏:延迟类宏作用于节点级 LLD 触发器,堆使用率宏作用于 JVM 告警,响应时间宏作用于 TCP 服务性能告警(默认 10 秒);
- 宏在模板描述中被标记为 "Text macro",在 Zabbix 5.0 中建议在主机级覆盖以避免模板冲突。
数据采集架构:master item 与 dependent item 协同
从 XML 导出的结构看,模板的数据流是典型的 "master → dependent" 模式。原始 JSON 采集由 4 个 Zabbix agent (web.page.get) 类型的 raw item 完成,均挂在 Zabbix raw items 应用下,历史与趋势均不保留(history: 0、trends: 0),仅作为数据源:
| Raw item 名称 | 采集键(Key) | 更新间隔 | 对应 REST API |
|---|---|---|---|
| ES: Get cluster health | web.page.get[{$ELASTICSEARCH.HOST},_cluster/health?timeout=5s,{$ELASTICSEARCH.PORT}] |
1m | GET /_cluster/health?timeout=5s |
| ES: Get cluster stats | web.page.get[{$ELASTICSEARCH.HOST},_cluster/stats,{$ELASTICSEARCH.PORT}] |
1m | GET /_cluster/stats |
| ES: Get nodes stats | web.page.get[{$ELASTICSEARCH.HOST},_nodes/stats,{$ELASTICSEARCH.PORT}] |
1m | GET /_nodes/stats |
| ES: Get index settings | web.page.get[{$ELASTICSEARCH.HOST},_settings,{$ELASTICSEARCH.PORT}] |
1m | GET /_settings |
这些 raw item 均带 REGEX 预处理(\n\s?\n(.*)),用于剥离 HTTP 响应头、提取纯 JSON 正文;_cluster/health 额外带了 timeout=5s 参数,避免健康检查长时间挂起。
所有派生指标均为 dependent item,Update: 0(无独立更新间隔,跟随 master item 节奏),并通过 master_item 字段声明其数据来源。例如:
es.cluster.delayed_unassigned_shards← masterweb.page.get[...,_cluster/health?timeout=5s,...],JSONPath 提取$.delayed_unassigned_shards;es.indices.count、es.nodes.count.data← master_cluster/stats;- 节点级
es.node.*系列 ← master_nodes/stats; es.index.read_only_allow_delete[{#ES.INDEX_NAME}]← master_settings。
单位换算示例(体现预处理的精妙之处):es.cluster.task_max_waiting_in_queue 从 $.task_max_waiting_in_queue_millis 提取后,叠加 MULTIPLIER 0.001 转换为秒;es.node.jvm.uptime 与 es.nodes.jvm.max_uptime 同样以 MULTIPLIER 0.001 将毫秒转为秒。而需要展示速率/增量的指标则使用 CHANGE_PER_SECOND(如线程池 completed/rejected 速率、query/fetch/refresh 速率)或 SIMPLE_CHANGE(如各类 throttled_time、refresh time 的时间增量)。
集群级监控项:健康、分片与容量
模板针对集群整体提供了约 20 个 dependent item,主要来自 _cluster/health 与 _cluster/stats:
集群健康维度(_cluster/health):
es.cluster.status:集群健康状态。经JAVASCRIPT预处理将green/yellow/red映射为0/1/2,未知值映射为255,再通过值映射ES cluster state展示(0→green、1→yellow、2→red、255→unknown);es.cluster.number_of_nodes/es.cluster.number_of_data_nodes:集群与数据节点总数;- 分片类:
es.cluster.relocating_shards(迁移中)、es.cluster.initializing_shards(初始化中)、es.cluster.unassigned_shards(未分配)、es.cluster.delayed_unassigned_shards(延迟分配); es.cluster.inactive_shards_percent_as_number:非活跃分片占比,由$.active_shards_percent_as_number经JAVASCRIPT计算100 - value得到;es.cluster.number_of_pending_tasks:待执行集群级变更数;es.cluster.task_max_waiting_in_queue:最早发起任务在队列中的等待秒数。
集群统计维度(_cluster/stats):
es.cluster_name[{#ES.NODE}]:集群名称(作者新增的采集项);es.indices.count:分配到所选节点的索引总数;es.indices.docs.count:非删除文档总数(基于 Lucene segments,含 nested 字段文档);es.nodes.count.master/es.nodes.count.data/es.nodes.count.ingest:具备 master / data / ingest 角色的节点数;es.nodes.fs.available_in_bytes/es.nodes.fs.total_in_bytes:全部节点文件系统可用字节与总字节(前者是 JVM 实际可用的磁盘空间);es.nodes.jvm.max_uptime[{#ES.NODE}]:自 JVM 上次启动以来的运行时长(秒)。
服务可用性维度(不依赖 REST API,走 TCP 探测):
net.tcp.service["{$ELASTICSEARCH.SCHEME}","{$ELASTICSEARCH.HOST}","{$ELASTICSEARCH.PORT}"]:服务是否存活并接受连接,经值映射Service state(0→Down、1→Up);net.tcp.service.perf["{$ELASTICSEARCH.SCHEME}","{$ELASTICSEARCH.HOST}","{$ELASTICSEARCH.PORT}"]:TCP 服务响应耗时(秒)。
低级别发现(LLD):节点与索引自动展开
模板内置两条发现规则,将集群拓扑自动映射为监控对象:
Cluster nodes discovery
- 类型:
Zabbix agent,键web.page.get[{$ELASTICSEARCH.HOST},_nodes/_all/nodes,{$ELASTICSEARCH.PORT}],更新间隔 1h; - LLD 宏:
{#ES.NODE}(通过lld_macro_path的$..name.first()从_nodes/_all/nodes响应中提取节点名); - 预处理:先
REGEX剥离响应头,再JSONPATH $.nodes.[*]展开节点数组; - 每个节点自动生成一个
ES {#ES.NODE}应用及数十个监控项原型(见下节),JSONPath 均使用过滤器$..[?(@.name=='{#ES.NODE}')]定位对应节点的数据段。
Index settings discovery
- 类型:
Dependent item,键es.index.settings(master 为web.page.get[...,_settings,...]),更新 0(跟随 master 的 1m 节奏); - LLD 宏:
{#ES.INDEX_NAME}(路径$..provided_name.first()); - 预处理:
JSONPATH $.[*]展开每个索引对象; - 为每个索引生成监控项原型
es.index.read_only_allow_delete[{#ES.INDEX_NAME}],其预处理链为:JSONPATH $..['{#ES.INDEX_NAME}'].settings.index.blocks.read_only_allow_delete.first()(带DISCARD_VALUE错误处理)→BOOL_TO_DECIMAL(true/false 转 1/0)→DISCARD_UNCHANGED_HEARTBEAT 1h。
节点级监控项:索引、搜索、JVM、线程池与文件系统
通过 Cluster nodes discovery,每个节点会展开约 40 个监控项原型,覆盖以下维度(键均带 [{#ES.NODE}] 后缀):
索引与写入:
es.node.indices.indexing.index_total/index_time_in_millis/index_current:索引操作总数、总耗时、当前执行数;es.node.indices.flush.total/flush.total_time_in_millis:flush 次数与总耗时;es.node.indices.refresh.rate/refresh.time:每秒 refresh 次数、refresh 耗时增量;es.node.indices.merges.total_throttled_time:merge 被限流的总时间;es.node.indices.recovery.throttle_time:recovery 被限流的时间。
搜索与查询:
es.node.indices.search.query_total/query_time_in_millis/query_current/query.rate/query_time:查询总量、总耗时、当前并发、每秒速率、周期耗时;es.node.indices.search.fetch_total/fetch_time_in_millis/fetch_current/fetch.rate/fetch_time:fetch 阶段对应指标。
JVM 内存:
es.node.jvm.mem.heap_committed_in_bytes/heap_max_in_bytes/heap_used_in_bytes/heap_used_percent:堆已提交、上限、已用、使用率;es.node.jvm.uptime:节点 JVM 运行秒数。
线程池(refresh / search / write 三类各 4 项):
es.node.thread_pool.<pool>.active:活跃线程数;es.node.thread_pool.<pool>.queue:队列中任务数;es.node.thread_pool.<pool>.completed.rate:每秒完成任务数;es.node.thread_pool.<pool>.rejected.rate:每秒被拒绝任务数(拒绝意味着队列饱和,是资源瓶颈的典型信号)。
文件系统与 HTTP:
es.node.fs.total.total_in_bytes/es.node.fs.total.available_in_bytes:节点文件系统总量与可用量;es.node.http.current_open/es.node.http.opened.rate:当前打开的 HTTP 连接数与每秒新建连接数。
计算型指标:四项延迟的推算公式
README 中标记为 Calculated 类型的 4 个延迟指标,是模板的亮点——它们不直接取 API 字段,而是由两个原始计数器相除得到"平均每次操作耗时":
| 指标 | 计算表达式(来自 XML 的 params) |
|---|---|
| Flush latency | last(es.node.indices.flush.total_time_in_millis[{#ES.NODE}]) / (last(es.node.indices.flush.total[{#ES.NODE}]) + (last(...total) = 0)) |
| Indexing latency | last(es.node.indices.indexing.index_time_in_millis[{#ES.NODE}]) / (last(es.node.indices.indexing.index_total[{#ES.NODE}]) + (last(...total) = 0)) |
| Fetch latency | last(es.node.indices.search.fetch_time_in_millis[{#ES.NODE}]) / (last(es.node.indices.search.fetch_total[{#ES.NODE}]) + (last(...total) = 0)) |
| Query latency | last(es.node.indices.search.query_time_in_millis[{#ES.NODE}]) / (last(es.node.indices.search.query_total[{#ES.NODE}]) + (last(...total) = 0)) |
表达式中 + (last(...) = 0) 部分在操作总数为 0 时兜底为 1,避免除零错误,这是一个值得在自建计算型指标时借鉴的写法。4 个指标单位均为 ms,更新间隔 1m,并分别驱动对应的延迟告警触发器。
触发器与告警策略
README 的 Triggers 章节列出了模板自带的全部告警,核心如下(LLD 原型触发器会在每个节点/索引上自动展开):
索引只读告警(高危):
Read-only index "{#ES.INDEX_NAME}":表达式es.index.read_only_allow_delete[{#ES.INDEX_NAME}].last()}=1,优先级 high。含义:磁盘水位触发 flood stage 后 ES 强制索引只读,数据写入将被阻断(索引仍允许删除以释放空间)。
延迟类告警(警告)——均为 5 分钟窗口最小值超过阈值:
- Flush latency:
{...flush.latency[...].min(5m)}>{$ELASTICSEARCH.FLUSH_LATENCY.MAX.WARN}(默认 100ms)。flush 延迟持续走高通常暗示磁盘性能劣化,可能最终阻止新数据写入; - Indexing latency:阈值
{$ELASTICSEARCH.INDEXING_LATENCY.MAX.WARN}。延迟上升通常意味着并发索引量过大,官方建议从 5–15 MB 的 bulk 批次起步、缓慢加大; - Fetch latency:阈值
{$ELASTICSEARCH.FETCH_LATENCY.MAX.WARN}。fetch 阶段理应远快于 query 阶段,持续升高提示慢磁盘、文档高亮(enriching)开销或请求返回结果过多; - Query latency:阈值
{$ELASTICSEARCH.QUERY_LATENCY.MAX.WARN}。超阈值时应排查资源瓶颈或优化查询。
JVM 堆告警:
Percent of JVM heap in use is high:{...heap_used_percent[...].min(1h)}>{$ELASTICSEARCH.HEAP_USED.MAX.WARN}(85%),warning;Percent of JVM heap in use is critical:{...min(1h)}>{$ELASTICSEARCH.HEAP_USED.MAX.CRIT}(95%),high,且作为上一触发器的依赖(避免重复报警)。说明 GC 速度跟不上对象产生速度,应对策略是调大堆(仍须遵循官方推荐上限)或横向扩容节点。
线程池拒绝告警(警告):refresh / search / write 三类线程池的 rejected.rate 5 分钟最小值大于 0 即告警,表示执行器队列已满、任务被丢弃。
节点重启告警(信息):{...jvm.uptime[...].last()}<10m,提示节点 JVM 重启过(manual_close 手动关闭)。
服务可用性告警(README 之外、XML 中可见的补充触发器):
ES: Service is down(average):net.tcp.service[...].last()}=0,服务不存活或不接受 TCP 连接;ES: Service response time is too high(warning):net.tcp.service.perf[...].min(5m)}>{$ELASTICSEARCH.RESPONSE_TIME.MAX.WARN},且依赖上面的 Service is down;ES: Health is RED / YELLOW / UNKNOWN(high / average / high):基于es.cluster.status的 0/1/2/255 值映射;ES: Cluster has the initializing shards、ES: Cluster has the unassigned shards(average):对应计数 10 分钟最小值大于 0;ES: The number of nodes within the cluster has decreased / increased(info):节点数变化通知;ES: Cluster has only two master nodes(disaster):仅剩 2 个 master 角色节点,任一宕机集群即不可用;ES: Cluster has been restarted (uptime < 10m)(info);ES: Cluster does not have enough space for resharding(high):表达式用(fs.total - fs.available)/(data_nodes - 1) > fs.available判断剩余空间不足以支撑分片迁移。
图形与值映射
模板预置了 1 张集群级图形与 5 张节点级图形原型:
ES: Cluster health:聚合非活跃分片占比、relocating / initializing / unassigned / delayed unassigned shards、pending tasks、task max waiting in queue 共 7 条线,是集群健康的总览图;ES {#ES.NODE}: Latency:query / indexing / fetch / flush 四项延迟对比;ES {#ES.NODE}: Query load:当前 fetch 与 query 并发数;ES {#ES.NODE}: Refresh / Search / Write thread pool:各线程池的 active、queue、completed.rate、rejected.rate。
值映射有两个:ES cluster state(0/1/2/255 → green/yellow/red/unknown)与 Service state(0/1 → Down/Up),分别服务于健康状态与 TCP 服务状态监控项。
部署与使用步骤
- 导入模板:在 Zabbix 前端「配置 → 模板」中导入对应版本的导出文件。Zabbix 5.0 使用 5.0 XML,5.4 与 6.0 分别使用仓库中对应目录下的 YAML 导出;该目录下各版本文件内容一致,仅导出格式随 Zabbix 版本演化;
- 关联主机:将模板链接到部署了 Zabbix agent 且能访问 Elasticsearch API 的主机(
App Elasticsearch Cluster by Zabbix agent属于Templates/Applications组); - 配置宏:若 ES 不在本机默认端口,在主机级覆盖
{$ELASTICSEARCH.HOST}、{$ELASTICSEARCH.PORT}、{$ELASTICSEARCH.SCHEME};启用认证时填写{$ELASTICSEARCH.USERNAME}与{$ELASTICSEARCH.PASSWORD}; - 验证数据:导入后等待 1–2 个采集周期(raw item 间隔 1m,LLD 间隔 1h),在「监测 → 最新数据」中确认
es.*指标有值; - 调整阈值:根据集群实际规模修改各
*.MAX.WARN/*.MAX.CRIT宏,避免告警风暴或漏报。
注意事项与适用前提
- 模板在 Zabbix 5.0 上设计,5.4/6.0 目录下提供的是同一模板的重新导出;在更高版本(7.x)导入前建议用官方工具校验导出格式兼容性;
- 采集依赖 Zabbix agent 对 ES 端口的网络可达性;
net.tcp.service系列探测的是 TCP 层连通,HTTP 层故障需结合 raw item 的 no data 状态判断; web.page.get类 raw item 不保留历史(history: 0),所有历史数据由 dependent item 承担,这是降低存储开销的刻意设计;- LLD 基于节点名(
{#ES.NODE})与索引名({#ES.INDEX_NAME})展开,节点或索引更名后会自动重建监控项; - 若 Elasticsearch 位于反向代理或 TLS 网关之后,需确保
{$ELASTICSEARCH.SCHEME}与实际协议一致,且 agent 所在主机信任对应证书。
小结
App Elasticsearch Cluster by Zabbix agent 以"一次 HTTP 拉取 + 多次 JSONPath 复用"的架构,实现了对 Elasticsearch 集群健康、分片、容量、节点 JVM、索引/搜索延迟、线程池饱和与只读索引的全方位监控,且全程无需外部脚本。其宏驱动的阈值体系、LLD 自动发现与计算型延迟指标,为自建应用监控模板提供了成熟范本。部署时对照 5.0 README 的宏表格与本文的采集架构说明,即可快速落地一套可用的 ES 集群监控方案。