企业官网建设流程全解析

Telegraf Icinga2 输入插件实战：通过 Icinga2 Remote API 采集主机与服务监控状态

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

本篇技术指南围绕 Telegraf 的inputs.icinga2输入插件展开，讲解如何借助 Icinga2 的 Remote API 将主机（hosts）、服务（services）状态以及 ApiListener、CIB、IDO 数据库连接等内部组件指标持续采集进 Telegraf 的指标管道。读完本文，你将掌握该插件的完整配置方法、三类指标（icinga2_hosts、icinga2_services、icinga2_status）的结构与含义，并理解其底层 API 调用与解析实现，从而在真实监控环境中快速落地 Icinga2 与 InfluxDB 等时序存储的集成方案。

插件概览：打通 Icinga2 与 Telegraf 的监控数据管道

inputs.icinga2是 Telegraf 内置的输入插件，其职责是通过 Icinga2 Remote API 拉取 Icinga2 实例中的主机与服务状态信息，以及组件级运行状态，再以普通 Telegraf 指标的形式注入采集管道。根据插件 README 与源码中的标记信息，该插件自Telegraf v1.8.0起提供，类别标签为network, server, system，支持所有平台（all）。

插件的数据来源分为两条 API 通道，均在 采集主流程 的Gather方法中按顺序请求：

1. /v1/objects端点：用于拉取主机（hosts）与服务（services）对象的状态，生成icinga2_hosts与icinga2_services指标；
2. /v1/status端点：用于拉取指定内部组件（ApiListener、CIB、IdoMysqlConnection、IdoPgsqlConnection）的运行指标，统一归并为icinga2_status指标。

该插件的注册入口位于 plugins/inputs/all/icinga2.go，通过构建标签!custom || inputs || inputs.icinga2控制是否编入；使用自定义构建器（custom builder）时，在输入插件列表中显式包含inputs.icinga2即可启用，默认全量构建时则自动注册。

插件启用与全局配置入口

inputs.icinga2与其他 Telegraf 插件一样，支持两类配置设置：

• 插件级通用选项：包括指标重命名、标签/字段过滤、别名与处理器顺序等，详见 docs/CONFIGURATION.md；
• 插件自身参数：即下文将要详述的server、objects、status等。

全局配置模板的说明段落引用自 docs/includes/plugin_config.md，在配置[[inputs.icinga2]]时可通过namepass、fieldpass、tagexclude、alias等通用选项对采集结果做进一步裁剪与改造。

配置详解

完整配置示例

插件配置模板由 sample.conf 提供，并嵌入到插件二进制的SampleConfig()方法中。以下是完整可用的配置骨架：

# Gather Icinga2 status [[inputs.icinga2]] ## Required Icinga2 server address # server = "https://localhost:5665" ## Collected Icinga2 objects ("services", "hosts") ## Specify at least one object to collect from /v1/objects endpoint. # objects = ["services"] ## Collect metrics from /v1/status endpoint ## Choose from: ## "ApiListener", "CIB", "IdoMysqlConnection", "IdoPgsqlConnection" # status = [] ## Credentials for basic HTTP authentication # username = "admin" # password = "admin" ## Maximum time to receive response. # response_timeout = "5s" ## Optional TLS Config # tls_ca = "/etc/telegraf/ca.pem" # tls_cert = "/etc/telegraf/cert.pem" # tls_key = "/etc/telegraf/key.pem" ## Use TLS but skip chain & host verification # insecure_skip_verify = true

配置参数说明

参数校验与默认值：源码层面的约束

在 Init 方法 中，插件对配置进行了两处硬性校验，理解它们可以避免运行时才发现配置错误：

• status与objects的取值都会通过internal/choice包的CheckSlice校验，非法值会以config option 'status': .../config option 'objects': ...的形式返回错误并导致插件初始化失败；
• response_timeout若小于 1 秒，会被强制覆盖为 5 秒默认值。

插件注册时的默认初始化（见 init）会预设Server = "https://localhost:5665"、Objects = ["services"]、ResponseTimeout = 5s，即"零配置"也能至少尝试采集服务状态。测试 TestIcinga2Default 验证了该默认初始化的有效性。

采集原理：底层 API 调用与数据解析

对象采集（/v1/objects）

插件为objects中每个对象类型构造如下请求地址：

{server}/v1/objects/{services|hosts}?attrs=name&attrs=display_name&attrs=state&attrs=check_command

其中服务（services）请求会额外追加&attrs=host_name（见 Gather），用于区分服务所属的主机。返回的 JSON 由resultObject结构解析，重点关注attrs中的check_command、display_name、name、state（数值）与host_name字段。

对象状态在 gatherObjects 中被转换为两列数据：

• state_code：取state数值的整数部分；
• state标签：通过插件内置的levels = ["ok", "warning", "critical", "unknown"]切片按下标映射为可读文本（源码见 icinga2.go 第 24 行）。

需要留意的是：README 中标注主机状态的取值为UP/DOWN，但从当前实现看，主机与服务共用同一套levels映射（如测试 TestGatherHostsStatus 中state: 2.0被映射为critical）。若你的 Icinga2 版本返回状态码语义不同，应结合返回数值与state_code字段进行判定。

source标签的取值与对象类型相关：services类型取自host_name（即服务所属主机），hosts类型则直接取自对象name。

组件状态采集（/v1/status）

当status配置了组件时，插件请求{server}/v1/status/{组件名}，并按组件类型选择不同的解析器：

• CIB：使用parseCIBResponse（源码），直接展开响应results[0].status映射中的全部键值对作为字段；
• ApiListener/IdoMysqlConnection/IdoPgsqlConnection：使用parsePerfdataResponse（源码），遍历results[0].perfdata数组。其标签规约为：若label中首次出现-字符，则取其后的子串作为字段名（例如idopgsqlconnection_ido-pgsql_queries_rate变为pgsql_queries_rate），否则原样使用。

所有icinga2_status指标都带有一个component标签，值为对应的组件名。

请求认证与传输层

• 认证：仅当配置了username时才附加 Basic Auth 头；
• 传输：HTTP 客户端由 createHTTPClient 构建，融合tls.ClientConfig.TLSConfig()生成的 TLS 配置与response_timeout超时设置，因此上文所有 TLS 参数最终都会作用于 API 请求；
• 每次Gather都会对配置的对象与组件依次发起 GET 请求，任一步骤出错即中止本次采集。

指标详解

icinga2_hosts

采集自/v1/objects/hosts端点：

• tags
  • check_command：检查命令的短名称
  • display_name：主机显示名称
  • state：状态（由数值经levels映射得到）
  • source：Icinga2 主机（即对象name）
  • port：Icinga2 端口（取自serverURL）
  • scheme：Icinga2 协议（http/https）
  • server：check_command所服务的服务器（即serverURL 的主机名）
• fields
  • name(string)
  • state_code(int)

icinga2_services

采集自/v1/objects/services端点：

• tags
  • check_command：检查命令的短名称
  • display_name：服务显示名称
  • state：服务状态 OK/WARNING/CRITICAL/UNKNOWN
  • source：服务所属主机（host_name）
  • port：Icinga2 端口
  • scheme：Icinga2 协议（http/https）
  • server：check_command所服务的服务器
• fields
  • name(string)
  • state_code(int)

icinga2_status

采集自/v1/status/{组件}端点，按组件细分字段（均带component标签）：

• ApiListener
  • api_num_conn_endpoints、api_num_endpoint、api_num_http_clients、api_num_json_rpc_anonymous_clients、api_num_json_rpc_relay_queue_item_rate、api_num_json_rpc_relay_queue_items、api_num_json_rpc_sync_queue_item_rate、api_num_json_rpc_sync_queue_items、api_num_json_rpc_work_queue_item_rate、api_num_not_conn_endpoints
• CIB
  • 检查执行情况：active_host_checks、active_host_checks_1min、active_host_checks_5min、active_host_checks_15min、active_service_checks、active_service_checks_1min、active_service_checks_5min、active_service_checks_15min、passive_host_checks、passive_host_checks_1min、passive_host_checks_5min、passive_host_checks_15min、passive_service_checks、passive_service_checks_1min、passive_service_checks_5min、passive_service_checks_15min
  • 性能统计：avg_execution_time、avg_latency、current_concurrent_checks、current_pending_callbacks、max_execution_time、max_latency、min_execution_time、min_latency
  • 主机计数：num_hosts_acknowledged、num_hosts_down、num_hosts_flapping、num_hosts_handled、num_hosts_in_downtime、num_hosts_pending、num_hosts_problem、num_hosts_unreachable、num_hosts_up
  • 服务计数：num_services_acknowledged、num_services_critical、num_services_flapping、num_services_handled、num_services_in_downtime、num_services_ok、num_services_pending、num_services_problem、num_services_unknown、num_services_unreachable、num_services_warning
  • 其他：remote_check_queue、uptime
• IdoMysqlConnection
  • mysql_queries_1min、mysql_queries_5mins、mysql_queries_15mins、mysql_queries_rate、mysql_query_queue_item_rate、mysql_query_queue_items
• IdoPgsqlConnection
  • pgsql_queries_1min、pgsql_queries_5mins、pgsql_queries_15mins、pgsql_queries_rate、pgsql_query_queue_item_rate、pgsql_query_queue_items

需要注意的是，CIB字段名与 API 返回的键名一一对应，若 Icinga2 版本升级导致status映射新增或删减键，指标字段会随之变化；而ApiListener与 IDO 连接类字段则取决于组件返回的 perfdata 标签。

查询与可视化示例

将采集结果写入 InfluxDB 后，可以用以下 SQL 快速筛查异常状态（以 24 小时窗口为例，源自插件 README）：

SELECT * FROM "icinga2_services" WHERE state_code = 0 AND time > now() - 24h -- 状态为 OK 的服务 SELECT * FROM "icinga2_services" WHERE state_code = 1 AND time > now() - 24h -- 状态为 WARNING 的服务 SELECT * FROM "icinga2_services" WHERE state_code = 2 AND time > now() - 24h -- 状态为 CRITICAL 的服务 SELECT * FROM "icinga2_services" WHERE state_code = 3 AND time > now() - 24h -- 状态为 UNKNOWN 的服务

同理，可用icinga2_hosts的state_code筛查主机异常，或用icinga2_status+component='CIB'观察num_services_problem、num_hosts_problem、avg_latency等容量与健康度指标。

输出样例

单条主机指标的行协议输出如下（摘录自 插件 README）：

icinga2_hosts,display_name=router-fr.eqx.fr,check_command=hostalive-custom,host=test-vm,source=localhost,port=5665,scheme=https,state=ok name="router-fr.eqx.fr",state=0 1492021603000000000

解析说明：state=ok与state=0分别对应state标签与state_code字段；host=test-vm是 Telegraf 全局注入的host标签（源自本机名），而source=localhost、port=5665、scheme=https则来自server配置项的解析结果。

测试与验证：源码级的采集行为佐证

插件自带的单元测试覆盖了主要采集路径，可作为理解行为与回归验证的参考（全部位于 icinga2_test.go）：

• TestGatherServicesStatus：使用httptest模拟/v1/objects/services响应，验证服务指标字段、source=host_name以及server/port/scheme标签的正确组装；
• TestGatherHostsStatus：验证主机指标采集，确认state: 2.0映射为critical、source取对象name；
• TestGatherStatusCIB：验证CIB组件把status映射原样展开为指标字段；
• TestGatherStatusPgsql：验证 perfdata 标签的-前缀剥离逻辑（idopgsqlconnection_ido-pgsql_queries_rate→pgsql_queries_rate）。

在本地无真实 Icinga2 环境时，可参照上述测试模式用轻量 HTTP 服务模拟 API 响应，快速验证插件行为。

常见问题与排查建议

• 采集不到icinga2_status：确认status配置的组件名是否为ApiListener、CIB、IdoMysqlConnection、IdoPgsqlConnection之一，拼写错误会在Init阶段直接报错。
• 认证失败：插件只在username非空时发送 Basic Auth，若仅配置password而不配置用户名，请求将不带任何认证头。
• HTTPS 证书报错：自签名证书环境请配置tls_ca指向服务端 CA；测试环境可临时开启insecure_skip_verify（仅限可信内网）。
• 响应超时：response_timeout最小 1 秒，若 Icinga2 实例在大量对象下响应缓慢，可适当调大该值；配置小于 1 秒会被静默重置为 5 秒。
• 状态语义对齐：主机状态在部分 Icinga2 版本中的取值与插件levels映射可能不完全一致，建议先查看原始state_code数值与state标签的对应关系再配置告警阈值。

通过本文的配置与源码解析，你可以把 Icinga2 的告警对象与内部运行状态无缝汇入 Telegraf 生态，与 InfluxDB、Grafana 等下游组件组合成完整的可观测性方案。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf