基于 Zabbix agent 的 Elasticsearch 集群监控模板:App Elasticsearch Cluster by Zabbix agent 深度解析

原创2026-10-15 19:56:471,940 阅读

基于 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 中明确说明):

  1. 增加只读索引检查:Elasticsearch 在磁盘空间不足(超过 flood stage 水位)时会把索引置为只读,模板通过 _settings 接口识别 index.blocks.read_only_allow_delete 状态并产生高优先级告警;
  2. 增加 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 ← master web.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 服务状态监控项。

部署与使用步骤

  1. 导入模板:在 Zabbix 前端「配置 → 模板」中导入对应版本的导出文件。Zabbix 5.0 使用 5.0 XML,5.4 与 6.0 分别使用仓库中对应目录下的 YAML 导出;该目录下各版本文件内容一致,仅导出格式随 Zabbix 版本演化;
  2. 关联主机:将模板链接到部署了 Zabbix agent 且能访问 Elasticsearch API 的主机(App Elasticsearch Cluster by Zabbix agent 属于 Templates/Applications 组);
  3. 配置宏:若 ES 不在本机默认端口,在主机级覆盖 {$ELASTICSEARCH.HOST}、{$ELASTICSEARCH.PORT}、{$ELASTICSEARCH.SCHEME};启用认证时填写 {$ELASTICSEARCH.USERNAME} 与 {$ELASTICSEARCH.PASSWORD};
  4. 验证数据:导入后等待 1–2 个采集周期(raw item 间隔 1m,LLD 间隔 1h),在「监测 → 最新数据」中确认 es.* 指标有值;
  5. 调整阈值:根据集群实际规模修改各 *.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 集群监控方案。

登录后查看全文
community-templates