Telegraf inputs.teamspeak 插件：通过 ServerQuery 协议监控 Teamspeak 3 语音服务器

Telegraf inputs.teamspeak 插件通过 ServerQuery 协议监控 Teamspeak 3 语音服务器【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本文以 plugins/inputs/teamspeak/README.md 为主体结合 teamspeak.go 的源码实现与 teamspeak_test.go 的测试用例完整讲解 Telegrafinputs.teamspeak插件的接入前提、配置参数、指标清单与底层采集链路帮助运维人员把 Teamspeak 3 语音服务器纳入统一的指标监控体系。一、插件定位只支持 Teamspeak 3 的 ServerQuery 采集teamspeak是一个输入插件用于通过ServerQuery接口采集一个或多个虚拟 Teamspeak 服务器的统计数据。根据插件 README 的明确说明目前仅支持 Teamspeak 3服务器插件自 Telegraf v1.5.0 引入归类于server类插件支持所有平台在插件注册文件 plugins/inputs/all/teamspeak.go 中通过_ github.com/influxdata/telegraf/plugins/inputs/teamspeak匿名导入完成注册默认随标准构建编译。ServerQuery 是 Teamspeak 3 提供的文本命令接口通常监听10011端口客户端登录后可发送serverinfo、serverrequestconnectioninfo等命令获取服务器状态。本插件正是基于该协议工作。二、接入前提ServerQuery 账户与 IP 白名单在配置 Telegraf 之前有两项 Teamspeak 服务端侧的准备工作这一点是生产环境最常见的坑创建 ServerQuery 专用账户Teamspeak 的常规用户不能直接执行 ServerQuery 命令需要在服务器管理端创建一个具备 ServerQuery 权限的账户如示例中的serverqueryuser并记录其用户名与密码供下文username/password使用。具体如何创建与授权可参考官方的Teamspeak 3 Server Query Manual。配置 IP 白名单README 中特别强调了一条注意事项——如果 Telegraf 从外部主机查询 Teamspeak 服务器必须把 Telegraf 所在主机加入 Teamspeak Server 安装目录下的query_ip_allowlist.txt文件否则 ServerQuery 连接会被服务器直接拒绝。三、完整配置说明以下是插件的完整示例配置源自 sample.conf# Reads metrics from a Teamspeak 3 Server via ServerQuery [[inputs.teamspeak]] ## Server address for Teamspeak 3 ServerQuery # server 127.0.0.1:10011 ## Username for ServerQuery username serverqueryuser ## Password for ServerQuery password secret ## Nickname of the ServerQuery client nickname telegraf ## Array of virtual servers # virtual_servers [1]各配置项的详细说明如下。其中“代码默认值”一列来自 teamspeak.go 中init()函数注册插件时的初始值配置项类型代码默认值说明serverstring127.0.0.1:10011Teamspeak 3 ServerQuery 接口地址host:portusernamestring无ServerQuery 账户用户名passwordstring无ServerQuery 账户密码nicknamestring无ServerQuery 客户端在服务器上的显示昵称virtual_servers[]int[1]要采集的虚拟服务器 ID 数组可配置多个此外插件支持 Telegraf 全部插件通用的全局配置项如过滤 tags/fields、别名、插件排序等详见 docs/CONFIGURATION.md。两点使用提示一台 Teamspeak 物理服务器上可以运行多个虚拟服务器vServer通过virtual_servers [1, 2, 3]即可在同一插件实例中批量采集nickname设置后该 ServerQuery 客户端会以指定昵称短暂出现在每个虚拟服务器中便于在服务端识别这是采集器而非普通用户。四、采集指标与标签插件以teamspeak为 metric 名称输出以下字段字段说明数据来源源码字段uptime虚拟服务器运行时长秒serverinfo的virtualserver_uptimeclients_online当前在线客户端数virtualserver_clientsonlinequery_clients_online当前在线的 ServerQuery 客户端数virtualserver_queryclientsonlinetotal_ping服务器总平均延迟virtualserver_total_pingtotal_packet_loss服务器总丢包率0~1 浮点virtualserver_total_packetloss_totalpackets_sent_totalServerQuery 连接累计发送包数serverrequestconnectioninfo的connection_packets_sent_totalpackets_received_totalServerQuery 连接累计接收包数connection_packets_received_totalbytes_sent_totalServerQuery 连接累计发送字节数connection_bytes_sent_totalbytes_received_totalServerQuery 连接累计接收字节数connection_bytes_received_total每条指标携带两个标签virtual_server虚拟服务器 ID数值转为字符串name虚拟服务器名称。五、输出示例插件 README 给出的真实输出示例InfluxDB line protocol 格式teamspeak,virtual_server1,nameLeopoldsServer,hostvm01 bytes_received_total29638202639i,uptime13567846i,total_ping26.89,total_packet_loss0,packets_sent_total415821252i,packets_received_total237069900i,bytes_sent_total55309568252i,clients_online11i,query_clients_online1i 1507406561000000000可以看到整数型计数器带i后缀uint64 类型total_ping、total_packet_loss为浮点host标签来自 Telegraf agent 全局配置非本插件产生。六、源码级实现分析采集主流程Gather核心逻辑位于 teamspeak.go 的Gather方法每个采集周期执行惰性连接插件用connected布尔标志维护连接状态。首次Gather时调用connect()建立连接若某次采集中途出错如服务器重启导致连接断开代码会执行ts.connected false使标志复位下个周期自动重连而不是让插件永久失效。逐虚拟服务器查询遍历VirtualServers数组对每个 vServer 依次执行三步ts.client.Use(vserver)——切换到目标虚拟服务器上下文ts.client.Server.Info()——执行serverinfo命令获得uptime、clients_online、total_ping、total_packet_loss、query_clients_onlinets.client.Server.ServerConnectionInfo()——执行serverrequestconnectioninfo命令获得四个累计包/字节计数。组装指标以virtual_servervServer ID和name服务器名为 tags通过acc.AddFields(teamspeak, fields, tags)提交指标。连接与登录connectconnect() 的实现通过第三方 Go 客户端库github.com/multiplay/go-ts3go.mod 中固定为 v1.2.0的ts3.NewClient(ts.Server)打开 TCP 连接并读取欢迎语调用ts.client.Login(ts.Username, ts.Password)完成认证若配置了nickname则对每个虚拟服务器执行UseSetNick把 ServerQuery 客户端的显示昵称设为指定值。从源码结构看该插件把协议解析完全委托给 go-ts3 库自身只负责“连接生命周期管理 命令编排 指标映射”代码量很小且逻辑清晰。测试如何模拟 ServerQuery 协议teamspeak_test.go 的做法值得参考测试在127.0.0.1:0上启动一个临时 TCP Listener在handleRequest中手工实现了 ServerQuery 协议的最小服务端——先发送TS3标记与欢迎语然后按命令前缀返回预设响应login、use→ 返回error id0 msgokserverinfo→ 返回包含virtualserver_clientsonline2、virtualserver_uptime148、virtualserver_total_ping1.0000、virtualserver_queryclientsonline1等字段的完整serverinfo报文serverrequestconnectioninfo→ 返回含connection_packets_sent_total369、connection_bytes_received_total17468等的连接信息报文。随后TestGather断言插件产出的字段与这些报文数值一一对应uptime148、clients_online2、total_ping1.0、packets_sent_total369等。这既验证了字段映射的正确性也间接说明了各指标在 ServerQuery 协议报文中的确切来源字段是排查“指标值不符合预期”问题时的最佳对照资料。七、适用场景与限制小结适用自托管 Teamspeak 3 服务器的可用性监控clients_online、uptime、网络质量观察total_ping、total_packet_loss以及 ServerQuery 通道自身的流量统计四个*_total累计字段。限制仅支持 TS3不支持 TS2/TS5插件通过 ServerQuery 通道获取的是该连接维度的累计计数packets_*/bytes_*来自serverrequestconnectioninfo并非全服所有用户流量的直接求和用于趋势观察而非精确容量核算——从测试用例与源码字段来源可以确认这一语义。部署检查清单创建 ServerQuery 账户 → 将 Telegraf 主机 IP 加入query_ip_allowlist.txt→ 确认10011端口可达 → 按第三节填写配置并确认virtual_servers覆盖全部 vServer ID。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考