Telegraf nginx_upstream_check 输入插件实战基于 Nginx 主动探测模块监控上游服务器健康状态【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的nginx_upstream_check输入插件自 Telegraf v1.10.0 引入专门用于采集 Nginx 中由第三方 nginx_upstream_check 模块提供的上游服务器主动健康探测数据。该插件会定期拉取 Nginx 状态页的 JSON 响应将每台上游服务器的存活/宕机状态、成功/失败探测计数转化为 Telegraf 指标。阅读本文后你将掌握该插件的完整配置方法、指标与标签结构、示例输出格式以及从源码层面理解其 HTTP 请求、JSON 解析与指标生成的完整调用链。插件工作原理Nginx 官方本身并不内置对 upstream 后端服务器的主动健康检查能力而第三方 nginx_upstream_check 模块通过在upstream块中配置check指令周期性地向各后端服务器发送配置好的请求支持 http/tcp 等类型并根据结果判定服务器可用性。该模块还会在 Nginx 中暴露一个状态查询入口通过check_status指令启用Telegraf 的nginx_upstream_check插件正是这个入口的消费方。插件的工作流程可以概括为三步运维人员将 nginx_upstream_check 模块编译进 Nginx在配置中为 upstream 块开启主动探测并暴露一个返回 JSON 格式的状态页Telegraf 按interval周期向配置的url发起 HTTP 请求默认GET超时默认 5 秒插件解析响应 JSON 中servers.server数组的每一条记录为每台上游服务器生成一条nginx_upstream_check测量值。从源码结构看插件主体 nginx_upstream_check.go 中的Gather方法是核心入口第 62–83 行它依次完成惰性创建并复用 HTTP 客户端 → 解析状态页 URL → 调用gatherStatusData拉取并转换数据。完整配置说明以下是该插件的完整示例配置与仓库中的 sample.conf 完全一致可直接复制使用# Read nginx_upstream_check module status information (https://github.com/yaoweibin/nginx_upstream_check_module) [[inputs.nginx_upstream_check]] ## An URL where Nginx Upstream check module is enabled ## It should be set to return a JSON formatted response url http://127.0.0.1/status?formatjson ## You can also point it at a unix socket too # url httpunix:///var/run/nginx.sock:/status?formatjson ## HTTP method # method GET ## Optional HTTP headers # headers {X-Special-Header Special-Value} ## Override HTTP Host header # host_header check.example.com ## Timeout for HTTP requests timeout 5s ## Optional HTTP Basic Auth credentials # username username # password pa$$word ## 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 false核心参数详解参数类型默认值说明urlstringhttp://127.0.0.1/status?formatjson必须指向 nginx_upstream_check 模块的状态页且需返回 JSON 格式响应。支持httpunix://前缀访问 Unix Socket如httpunix:///var/run/nginx.sock:/status?formatjsonmethodstringGETHTTP 请求方法源码中未设置时回退为GETheadersmap空表附加的 HTTP 请求头逐条通过Header.Add写入请求host_headerstring空不覆盖覆盖请求的 HTTPHost头用于 Nginx 按server_name虚拟主机路由的场景timeoutduration5sHTTP 请求超时底层客户端在未设置时也会回退为 5 秒username/passwordstring空配置后自动附加 HTTP Basic Auth 认证头tls_ca/tls_cert/tls_keystring空标准 TLS 证书配置insecure_skip_verifyboolfalse跳过 TLS 证书链与主机名校验这些默认值可以从 newNginxUpstreamCheck 工厂函数 得到印证URL默认http://127.0.0.1/status?formatjson、Method默认GET、Timeout默认5s。插件结构体 NginxUpstreamCheck 还内嵌了common_http.HTTPClientConfig这意味着除示例中列出的参数外该插件还继承了 Telegraf 通用 HTTP 客户端的完整能力包括 OAuth2 认证、Cookie 认证、代理以及连接池调优idle_conn_timeout、max_idle_conn等其定义见 plugins/common/http/config.go。关于 Unix Socket 支持并非空话通用 HTTP 客户端在CreateClient中显式注册了httpunix/httpsunix协议处理器config.go 第 82 行因此url httpunix:///var/run/nginx.sock:/status?formatjson这类写法可以直接工作。指标与标签结构插件生成的测量值名称固定为nginx_upstream_check每台被探测的上游服务器生成一条指标。字段Fields字段类型说明fall计数器uint64检查失败的累计次数rise计数器uint64检查成功的累计次数status字符串服务器当前状态up/down等status_code整型uint8状态码映射1- up2- down0- 其他README 中特别指出status_code通常是最好用的字段它允许你判断每一台服务器的当前状态并据此配置告警。虽然 InfluxDB 支持字符串字段可以直接用status但大多数其他监控方案更适合使用整型代码。这个映射关系在源码中的实现非常直观——getStatusCode 函数 对up返回 1对down返回 2其余情况返回 0。标签Tags所有测量值都携带以下标签标签说明name上游服务器的主机名或 IP含端口形如192.168.0.1:8080port备用检查端口使用默认端口时为0type检查类型http或tcpupstreamNginx 配置中 upstream 块的名称urlTelegraf 实际使用的状态页 URL标签与字段的生成逻辑集中在 gatherStatusData 方法它遍历 JSON 响应中servers.server数组的每一项逐项构建标签表和字段表后调用accumulator.AddFields(nginx_upstream_check, fields, tags)写入指标。示例输出按 README 所述运行以下命令./telegraf --config telegraf.conf --input-filter nginx_upstream_check --test可以得到如下结果--test表示只执行一次采集并打印结果nginx_upstream_check,hostnode1,name192.168.0.1:8080,port0,typehttp,upstreammy_backends,urlhttp://127.0.0.1:80/status?format\json fall0i,rise100i,statusup,status_code1i 1529088524000000000 nginx_upstream_check,hostnode2,name192.168.0.2:8080,port0,typehttp,upstreammy_backends,urlhttp://127.0.0.1:80/status?format\json fall100i,rise0i,statusdown,status_code2i 1529088524000000000可以看到第一条指标对应一台健康的后端rise100i、statusup、status_code1i第二条对应一台宕机的后端fall100i、statusdown、status_code2i。注意输出中的url标签对做了反斜杠转义这是 InfluxDB line protocol 对标签值中特殊字符的常规转义。源码解析一次采集的完整调用链结合 nginx_upstream_check.go 的源码一次完整采集的调用链如下HTTP 客户端的惰性初始化Gather首次执行时调用createHTTPClient第 86–95 行通过内嵌的HTTPClientConfig.CreateClient构建带 TLS、代理、超时等设置的*http.Client并缓存到check.client后续采集周期复用避免重复建连请求构造与发送gatherJSONData 方法 按配置确定 HTTP 方法默认GET依次附加 Basic Auth、自定义请求头与Host头后发出请求错误处理细节若响应状态码非 200插件会读取响应体前 200 字节io.LimitReader(response.Body, 200)拼入错误信息返回便于排查状态页 404/500 等问题第 127–131 行JSON 解码与映射响应体解码到nginxUpstreamCheckData结构其内部镜像了状态页 JSON 的servers→server[]结构包含upstream、name、status、rise、fall、type、port等字段第 39–56 行随后逐条转换为 Telegraf 指标。测试用例对行为的验证仓库自带的测试文件 nginx_upstream_check_test.go 用httptest模拟了 Nginx 状态页覆盖了上述行为TestNginxUpstreamCheckData第 44–102 行构造含两台服务器一台up/http一台down/tcp且使用备用端口 8080的 JSON 响应断言生成的标签upstream、type、name、port、url与字段status、status_code、rise、fall与预期完全一致其中status_code按up→1、down→2映射TestNginxUpstreamCheckRequest第 104–154 行在模拟服务端的处理函数中校验MethodPOST、自定义请求头X-Test、Basic Auth 生成的Authorization: Basic头以及Host: status.local均被正确发送到请求上验证了method、headers、username/password、host_header四个参数确实生效。前置条件与使用限制使用该插件需要满足以下前提否则采集会失败Nginx 必须编译并加载 nginx_upstream_check 模块并在upstream块中配置主动探测指令如检查间隔、连续成功/失败阈值、检查类型 http/tcp插件本身不发起对后端服务器的探测只读取模块统计的结果探测策略由 Nginx 侧决定状态页必须返回 JSON 格式因此 URL 通常携带?formatjson之类的查询参数具体参数形式以所安装模块版本为准注意状态页暴露面状态页包含完整的上游拓扑信息建议仅允许受信任地址如本机访问Telegraf 侧可配合username/passwordBasic Auth 进一步加固该插件的采集频率由 Telegraf 的全局interval或插件级interval控制它反映的是模块计数器在每个采集周期的快照rise/fall为模块内部累计值如需每周期新增失败次数可结合first/diff等聚合器或下游查询处理。更多通用插件配置如字段/标签过滤、别名、pass/name_override等参见 CONFIGURATION.md插件源码与示例配置分别位于 nginx_upstream_check.go 和 sample.conf官方说明见 插件 README。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Telegraf nginx_upstream_check 输入插件实战：基于 Nginx 主动探测模块监控上游服务器健康状态
Telegraf nginx_upstream_check 输入插件实战基于 Nginx 主动探测模块监控上游服务器健康状态【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的nginx_upstream_check输入插件自 Telegraf v1.10.0 引入专门用于采集 Nginx 中由第三方 nginx_upstream_check 模块提供的上游服务器主动健康探测数据。该插件会定期拉取 Nginx 状态页的 JSON 响应将每台上游服务器的存活/宕机状态、成功/失败探测计数转化为 Telegraf 指标。阅读本文后你将掌握该插件的完整配置方法、指标与标签结构、示例输出格式以及从源码层面理解其 HTTP 请求、JSON 解析与指标生成的完整调用链。插件工作原理Nginx 官方本身并不内置对 upstream 后端服务器的主动健康检查能力而第三方 nginx_upstream_check 模块通过在upstream块中配置check指令周期性地向各后端服务器发送配置好的请求支持 http/tcp 等类型并根据结果判定服务器可用性。该模块还会在 Nginx 中暴露一个状态查询入口通过check_status指令启用Telegraf 的nginx_upstream_check插件正是这个入口的消费方。插件的工作流程可以概括为三步运维人员将 nginx_upstream_check 模块编译进 Nginx在配置中为 upstream 块开启主动探测并暴露一个返回 JSON 格式的状态页Telegraf 按interval周期向配置的url发起 HTTP 请求默认GET超时默认 5 秒插件解析响应 JSON 中servers.server数组的每一条记录为每台上游服务器生成一条nginx_upstream_check测量值。从源码结构看插件主体 nginx_upstream_check.go 中的Gather方法是核心入口第 62–83 行它依次完成惰性创建并复用 HTTP 客户端 → 解析状态页 URL → 调用gatherStatusData拉取并转换数据。完整配置说明以下是该插件的完整示例配置与仓库中的 sample.conf 完全一致可直接复制使用# Read nginx_upstream_check module status information (https://github.com/yaoweibin/nginx_upstream_check_module) [[inputs.nginx_upstream_check]] ## An URL where Nginx Upstream check module is enabled ## It should be set to return a JSON formatted response url http://127.0.0.1/status?formatjson ## You can also point it at a unix socket too # url httpunix:///var/run/nginx.sock:/status?formatjson ## HTTP method # method GET ## Optional HTTP headers # headers {X-Special-Header Special-Value} ## Override HTTP Host header # host_header check.example.com ## Timeout for HTTP requests timeout 5s ## Optional HTTP Basic Auth credentials # username username # password pa$$word ## 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 false核心参数详解参数类型默认值说明urlstringhttp://127.0.0.1/status?formatjson必须指向 nginx_upstream_check 模块的状态页且需返回 JSON 格式响应。支持httpunix://前缀访问 Unix Socket如httpunix:///var/run/nginx.sock:/status?formatjsonmethodstringGETHTTP 请求方法源码中未设置时回退为GETheadersmap空表附加的 HTTP 请求头逐条通过Header.Add写入请求host_headerstring空不覆盖覆盖请求的 HTTPHost头用于 Nginx 按server_name虚拟主机路由的场景timeoutduration5sHTTP 请求超时底层客户端在未设置时也会回退为 5 秒username/passwordstring空配置后自动附加 HTTP Basic Auth 认证头tls_ca/tls_cert/tls_keystring空标准 TLS 证书配置insecure_skip_verifyboolfalse跳过 TLS 证书链与主机名校验这些默认值可以从 newNginxUpstreamCheck 工厂函数 得到印证URL默认http://127.0.0.1/status?formatjson、Method默认GET、Timeout默认5s。插件结构体 NginxUpstreamCheck 还内嵌了common_http.HTTPClientConfig这意味着除示例中列出的参数外该插件还继承了 Telegraf 通用 HTTP 客户端的完整能力包括 OAuth2 认证、Cookie 认证、代理以及连接池调优idle_conn_timeout、max_idle_conn等其定义见 plugins/common/http/config.go。关于 Unix Socket 支持并非空话通用 HTTP 客户端在CreateClient中显式注册了httpunix/httpsunix协议处理器config.go 第 82 行因此url httpunix:///var/run/nginx.sock:/status?formatjson这类写法可以直接工作。指标与标签结构插件生成的测量值名称固定为nginx_upstream_check每台被探测的上游服务器生成一条指标。字段Fields字段类型说明fall计数器uint64检查失败的累计次数rise计数器uint64检查成功的累计次数status字符串服务器当前状态up/down等status_code整型uint8状态码映射1- up2- down0- 其他README 中特别指出status_code通常是最好用的字段它允许你判断每一台服务器的当前状态并据此配置告警。虽然 InfluxDB 支持字符串字段可以直接用status但大多数其他监控方案更适合使用整型代码。这个映射关系在源码中的实现非常直观——getStatusCode 函数 对up返回 1对down返回 2其余情况返回 0。标签Tags所有测量值都携带以下标签标签说明name上游服务器的主机名或 IP含端口形如192.168.0.1:8080port备用检查端口使用默认端口时为0type检查类型http或tcpupstreamNginx 配置中 upstream 块的名称urlTelegraf 实际使用的状态页 URL标签与字段的生成逻辑集中在 gatherStatusData 方法它遍历 JSON 响应中servers.server数组的每一项逐项构建标签表和字段表后调用accumulator.AddFields(nginx_upstream_check, fields, tags)写入指标。示例输出按 README 所述运行以下命令./telegraf --config telegraf.conf --input-filter nginx_upstream_check --test可以得到如下结果--test表示只执行一次采集并打印结果nginx_upstream_check,hostnode1,name192.168.0.1:8080,port0,typehttp,upstreammy_backends,urlhttp://127.0.0.1:80/status?format\json fall0i,rise100i,statusup,status_code1i 1529088524000000000 nginx_upstream_check,hostnode2,name192.168.0.2:8080,port0,typehttp,upstreammy_backends,urlhttp://127.0.0.1:80/status?format\json fall100i,rise0i,statusdown,status_code2i 1529088524000000000可以看到第一条指标对应一台健康的后端rise100i、statusup、status_code1i第二条对应一台宕机的后端fall100i、statusdown、status_code2i。注意输出中的url标签对做了反斜杠转义这是 InfluxDB line protocol 对标签值中特殊字符的常规转义。源码解析一次采集的完整调用链结合 nginx_upstream_check.go 的源码一次完整采集的调用链如下HTTP 客户端的惰性初始化Gather首次执行时调用createHTTPClient第 86–95 行通过内嵌的HTTPClientConfig.CreateClient构建带 TLS、代理、超时等设置的*http.Client并缓存到check.client后续采集周期复用避免重复建连请求构造与发送gatherJSONData 方法 按配置确定 HTTP 方法默认GET依次附加 Basic Auth、自定义请求头与Host头后发出请求错误处理细节若响应状态码非 200插件会读取响应体前 200 字节io.LimitReader(response.Body, 200)拼入错误信息返回便于排查状态页 404/500 等问题第 127–131 行JSON 解码与映射响应体解码到nginxUpstreamCheckData结构其内部镜像了状态页 JSON 的servers→server[]结构包含upstream、name、status、rise、fall、type、port等字段第 39–56 行随后逐条转换为 Telegraf 指标。测试用例对行为的验证仓库自带的测试文件 nginx_upstream_check_test.go 用httptest模拟了 Nginx 状态页覆盖了上述行为TestNginxUpstreamCheckData第 44–102 行构造含两台服务器一台up/http一台down/tcp且使用备用端口 8080的 JSON 响应断言生成的标签upstream、type、name、port、url与字段status、status_code、rise、fall与预期完全一致其中status_code按up→1、down→2映射TestNginxUpstreamCheckRequest第 104–154 行在模拟服务端的处理函数中校验MethodPOST、自定义请求头X-Test、Basic Auth 生成的Authorization: Basic头以及Host: status.local均被正确发送到请求上验证了method、headers、username/password、host_header四个参数确实生效。前置条件与使用限制使用该插件需要满足以下前提否则采集会失败Nginx 必须编译并加载 nginx_upstream_check 模块并在upstream块中配置主动探测指令如检查间隔、连续成功/失败阈值、检查类型 http/tcp插件本身不发起对后端服务器的探测只读取模块统计的结果探测策略由 Nginx 侧决定状态页必须返回 JSON 格式因此 URL 通常携带?formatjson之类的查询参数具体参数形式以所安装模块版本为准注意状态页暴露面状态页包含完整的上游拓扑信息建议仅允许受信任地址如本机访问Telegraf 侧可配合username/passwordBasic Auth 进一步加固该插件的采集频率由 Telegraf 的全局interval或插件级interval控制它反映的是模块计数器在每个采集周期的快照rise/fall为模块内部累计值如需每周期新增失败次数可结合first/diff等聚合器或下游查询处理。更多通用插件配置如字段/标签过滤、别名、pass/name_override等参见 CONFIGURATION.md插件源码与示例配置分别位于 nginx_upstream_check.go 和 sample.conf官方说明见 插件 README。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考