Telegraf inputs.sip 插件实战对 SIP/VoIP 服务器做健康探测与延迟监控【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 自 v1.38.0 起提供inputs.sip输入插件通过向 SIPSession Initiation Protocol服务器发送 OPTIONS 等探测请求来监测 PBX 系统、SIP 代理、注册服务器和 VoIP 服务商的可用性与响应时延。本文以该插件的官方文档 plugins/inputs/sip/README.md 为主线完整覆盖其配置参数、SIP 方法选择、指标结构与排错方法并结合源码 plugins/inputs/sip/sip.go 和测试 plugins/inputs/sip/sip_test.go 深入讲解请求构造、摘要认证与超时处理的底层实现帮助你在部署 VoIP 基础设施时快速搭建一套可落地的 SIP 健康监控方案。插件概述与适用场景inputs.sip是一个主动探测型active probe插件它的工作模式非常直白按采集周期向配置好的 SIP 服务器发送 SIP 请求默认OPTIONS方法测量从发出请求到收到响应的时间并记录 SIP 状态码与原因短语将结果写入名为sip的 measurement供后续告警、聚合与可视化使用。插件标注分类为network平台为all所有平台均可用。它适用于以下典型场景监控 Asterisk、FreeSWITCH 等 PBX 或 SIP 代理的存活与延迟监测 SIP 注册服务器对 OPTIONS 的响应能力验证需要摘要认证Digest Authentication的 VoIP 服务的可达性使用 TLSsips://加密通道探测的合规性检查。插件基于第三方 Go 库github.com/emiago/sipgo当前仓库 go.mod 中版本为 v1.6.0实现 SIP 协议栈插件在 plugins/inputs/all/sip.go 中完成注册可通过telegraf --test等常规方式验证。完整配置参考以下配置完整继承自插件的示例配置 plugins/inputs/sip/sample.conf可直接复制到 Telegraf 主配置文件中# SIP (Session Initiation Protocol) health check plugin [[inputs.sip]] ## SIP server address to monitor ## Format: sip://host[:port] or sips://host[:port] ## sip:// - Standard SIP (default port 5060) ## sips:// - Secure SIP with TLS (default port 5061) server sip://sip.example.com:5060 ## Transport protocol ## Valid values: udp, tcp, ws, wss # transport udp ## SIP method to use for health checks ## Valid values: OPTIONS, INVITE, MESSAGE # method OPTIONS ## Request timeout # timeout 5s ## From user as it appears in SIP header # from_user telegraf ## From domain (domain part of From header) ## If not specified, uses the server hostname # from_domain ## To user as it appears in SIP header ## If not specified, uses the same value as from_user # to_user ## Local address to use for outgoing requests # local_address ## SIP digest authentication credentials ## Leave empty to use no authentication # username # password ## Optional TLS Config (only used for sips:// URLs or transporttls/wss) ## Set to true/false to enforce TLS being enabled/disabled. If not set, ## enable TLS only if any of the other options are specified. # tls_enable ## Trusted root certificates for server # tls_ca /path/to/cafile ## Used for TLS client certificate authentication # tls_cert /path/to/certfile ## Used for TLS client certificate authentication # tls_key /path/to/keyfile ## Password for the key file if it is encrypted # tls_key_pwd ## Send the specified TLS server name via SNI # tls_server_name kubernetes.example.com ## Minimal TLS version to accept by the client # tls_min_version TLS12 ## List of ciphers to accept, by default all secure ciphers will be accepted ## Use all, secure and insecure to add all support ciphers, secure ## suites or insecure suites respectively. # tls_cipher_suites [secure] ## Renegotiation method, never, once or freely # tls_renegotiation_method never ## Use TLS but skip chain host verification # insecure_skip_verify false参数详解与默认值结合 sip.go 中Init()与init()的源码各参数的实际默认值与语义如下参数默认值说明server必填被监测服务器地址格式sip://host[:port]或sips://host[:port]省略端口时分别默认 5060 / 5061transportsip://时默认udpsips://时默认tcp传输层协议合法取值udp、tcp、ws、wssmethodOPTIONS探测使用的 SIP 方法合法取值OPTIONS、INVITE、MESSAGE大小写敏感全大写timeout5s单次请求超时时间不允许为负值from_usertelegrafSIPFrom头中的用户部分from_domain服务器主机名SIPFrom头中的域名部分to_user与from_user相同SIPTo头中的用户部分local_address空指定本地出口地址会同时影响 Via 头主机名与 Contact 头username/password空不认证SIP 摘要认证凭据支持 secret store 注入tls_*系列见示例标准 Telegraf TLS 配置仅在sips://安全模式下生效几点值得注意的实现细节均可在 sip.go 的Init()中确认scheme 与 transport 的合法性是强约束。sip://只允许非安全传输udp/tcp/wssips://只允许安全传输tcp/wss任何不匹配组合都会导致插件初始化失败并报错而非静默降级。tls作为 transport 取值已被拒绝。源码注释明确说明tls传输已按 RFC 3261 弃用应改用sips://scheme测试用例TestInitRejectsDeprecatedTLSTransportsip_test.go专门验证了这一点。方法名大小写敏感。TestInitInvalidMethodCasesip_test.go验证了options、OpTiOnS等写法都会报invalid SIP method错误。凭据字段使用config.Secret类型即username与password支持 secret store配置方式参见 docs/CONFIGURATION.md 的 Secret store secrets 小节无需把明文密码写入配置文件。server 地址与端口规则从TestParseServer的测试用例sip_test.go可以看到地址解析的完整行为server 配置解析结果sip://sip.example.com:5060hostsip.example.com, port5060, 非安全sips://sip.example.com:5061hostsip.example.com, port5061, 启用 TLSsip://sip.example.com无端口默认 port5060sips://secure.example.com无端口默认 port5061 且强制 TLSsip://192.168.1.100:5070支持 IP 地址与非标准端口使用sips://时即使一个 TLS 参数都不设置插件也会强制启用 TLS采用系统默认证书链这是Init()中的显式行为ClientConfig.Enable未设置时会被置为true见 sip.go。SIP 探测方法选择插件支持三种 SIP 方法对应文档中的说明OPTIONS推荐标准 SIP 能力查询方法查询服务器能力而不建立会话对服务器无副作用是健康检查的首选。INVITE发起会话建立。文档明确提示需谨慎使用因为它可能在服务器上产生通话记录call records。MESSAGE发送即时消息适合验证消息类基础设施的连通性。测试代码TestSIPMethodINVITE、TestSIPMethodMESSAGE通过只注册对应方法的 mock 服务器来验证插件确实按配置发送了相应方法。注意如果目标服务器不响应你选择的方法例如仅接受 OPTIONS你会观察到503 Service Unavailable之类的状态码这属于配置排查项而非插件缺陷。指标说明与示例输出插件产生 measurement 名sip的指标Tags标签source配置的 SIP 服务器地址server原值method使用的 SIP 方法小写形式options/invite/messagetransport传输协议udp/tcp/ws/wssstatus_codeSIP 响应状态码如200、404超时场景下不存在该 tag。Fields字段response_time_sfloat秒收到响应所耗时超时场景下等于配置的timeout值resultstring请求结果。收到响应时为 SIP 原因短语如OK、Not Found、Unauthorized无有效响应时取哨兵值Timeout、Error或No Responseserver_agentstring可选响应中Server头的值标识远端服务器软件例如Asterisk PBX 18.15.0。文档给出的示例输出原样继承自 READMEsip,hosttelegraf-host,methodoptions,sourcesip://sip.example.com:5060,status_code200,transportudp response_time_s0.023,resultOK 1640000000000000000 sip,hosttelegraf-host,methodoptions,sourcesip://unreachable.example.com:5060,transportudp response_time_s5.0,resultTimeout 1640000000000000000 sip,hosttelegraf-host,methodoptions,sourcesip://sip.provider.com:5060,status_code404,transportudp response_time_s0.045,resultNot Found 1640000000000000000 sip,hosttelegraf-host,methodoptions,sourcesips://secure.voip.example.com:5061,status_code200,transporttcp response_time_s0.067,resultOK,server_agentAsterisk PBX 18.15.0 1640000000000000000注意第二行超时样本没有status_codetagresponse_time_s恰好等于配置的 5 秒超时值——这两点与源码中context.DeadlineExceeded分支的行为完全一致sip.go测试TestSIPServerTimeout也断言了response_time_s与超时值在 0.01 秒内相等。源码解析请求是如何构造和发送的生命周期Init / Start / Gather插件遵循 Telegraf service input 的三段式生命周期Init()sip.go填充默认值、校验server/method/transport合法性、解析出hostport并把可复用的请求组件缓存下来——requestURI含transportURI 参数以及To、User-Agent头。User-Agent头使用internal.ProductToken()即标准 Telegraf 产品标识。Start()sip.go创建 sipgo 的UserAgent与Client。如果配置了local_address会以sipgo.WithClientHostname选项将其作为 Via 头的主机名——这一行为正是 CHANGELOG.md 中记录的local_address用途。Gather()sip.go每次采集周期执行一次探测。From 头为什么不缓存Gather()中每次请求都会重新构造From头并追加一个 16 位随机 tagsip.GenerateTagN(16)源码注释解释了原因From tag 每次请求必须动态生成无法像其他头那样在Init()阶段缓存。这也是 SIP 协议避免事务冲突的常规做法。摘要认证两轮请求机制当配置了username/password且服务器返回401或407时插件走 SIP 摘要认证流程sip.go第一次请求不携带认证信息服务器返回401/407挑战含WWW-Authenticate头与 nonce插件取出凭据config.Secret的Get()取值后显式Destroy()释放调用 sipgo 的DoDigestAuth携带 Digest 凭据重发同一请求。由于 SIP 摘要认证必须先拿到服务器挑战中的 nonce 才能计算响应首次请求无法预认证——源码注释对此有明确说明。测试TestSIPAuthenticationSuccesssip_test.go验证了服务器恰好被调用两次初始请求 认证重试最终指标为status_code200, resultOK。一个安全相关的测试断言值得留意该测试遍历最终指标的所有 tag 和 field确认用户名和口令字符串绝不出现在任何输出字段中避免凭据泄漏到指标系统。失败路径的分类处理Gather()对失败做了精细区分且所有失败都返回 nil 而不是错误——即探测失败本身不会让插件退出而是转化为指标值场景result字段response_time_sstatus_codetag正常收到响应SIP 原因短语如OK实际耗时有超过timeoutTimeout等于配置超时值无传输层/其他错误Error实际耗时无响应对象为 nilNo Response实际耗时无这种设计使得你可以直接用result字段或status_code是否存在来编写告警例如result ! OK且持续 N 个周期即触发告警。测试如何验证整个链路sip_test.go 使用 sipgo 库在本地起了一个真实的 UDP mock SIP 服务器监听127.0.0.1的随机端口覆盖了插件的关键行为默认值TestInitDefaults验证OPTIONS/telegraf/udp默认值URL 解析TestParseServer验证 6 组地址/端口/scheme 组合TLS 行为TestTLSConfiguration、TestTLSServerName、TestSecureProtocolWithoutTLSConfig验证sips://触发 TLS 选项、sip://不触发以及 SNI 配置响应状态码TestSIPServerSuccess200、TestSIPServerErrorResponse404、TestSIPDifferentStatusCodes200/404/503验证 status_code tag 与 reason 短语映射超时与延迟TestSIPServerTimeout服务器故意不响应与TestSIPServerDelayedResponse延迟 50ms 响应验证时间测量与超时哨兵值认证TestSIPAuthenticationRequired无凭据时如实上报 401与TestSIPAuthenticationSuccess有凭据时完成两轮认证并验证凭据不泄漏。这些测试的存在意味着文档中描述的每一种响应行为包括404 可能仍代表服务器健康这类细微语义都有对应的自动化验证可以直接用go test ./plugins/inputs/sip/...复现。故障排查以下内容继承自官方 README 的 Troubleshooting 小节并结合源码行为补充。权限问题某些 SIP 实现可能需要特定网络权限。若遇到权限错误请确认 Telegraf 进程具备相应的网络访问能力。防火墙配置请确保允许到 SIP 端口通常 5060/5061的出站连接若使用 UDP防火墙需放行 UDP 包允许该事务的返回流量UDP 无连接返回包必须能回到探测方。超时问题如果出现频繁超时指标中resultTimeout且response_time_s恒等于 timeout 值增大timeout取值确认到 SIP 服务器的网络连通性检查 SIP 服务器是否配置为响应你所选择的方法如服务器不处理 OPTIONS 会返回 503确认选择了正确的transportUDP 服务器配 TCP 会收不到响应。响应码判读不同 SIP 服务器对 OPTIONS 的响应码可能不同200 OK— 服务器运行正常且在响应404 Not Found— 用户或资源不存在但这往往仍表示服务器本身健康插件默认探测to_user常为telegraf服务器不认识该用户是正常现象401 Unauthorized/407 Proxy Authentication Required— 需要认证。未配置凭据时插件会如实上报 401配置凭据后正常路径是最终上报 200。因此设计告警规则时建议把200、404都视为服务器存活把Timeout/Error/No Response以及503等视为异常。集成步骤小结将插件纳入现有 Telegraf 部署只需三步在 Telegraf 配置文件中添加[[inputs.sip]]段按上文参数表设置server必填与按需的method、timeout、认证与 TLS 项用telegraf --test或telegraf --config 你的配置试运行确认sip指标按预期输出可对照上文的示例输出在输出端配置告警关注result字段Timeout/Error/No Response为异常哨兵值与response_time_s的趋势变化。该插件的演进记录可在 CHANGELOG.md 中追溯插件本身由上游 PR #18183 引入后续 PR #18569 补充了local_address对 Via 头主机名的支持。若需了解其他输入/输出插件的通用配置标签、字段过滤、插件顺序等参见 docs/CONFIGURATION.md。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考