ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

Telegraf Socket Writer 输出插件完全指南:通过 TCP/UDP/Unix Socket 发送指标数据

Telegraf Socket Writer 输出插件完全指南:通过 TCP/UDP/Unix Socket 发送指标数据 Telegraf Socket Writer 输出插件完全指南通过 TCP/UDP/Unix Socket 发送指标数据【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafSocket Writer 是 Telegraf 中一个通用的网络输出插件负责将采集到的指标以用户指定的数据格式如 InfluxDB Line Protocol、JSON、Graphite 等写入任意网络服务支持 TCP、UDP、Unix Socket 与 vsock 等多种传输协议。读完本文你将掌握该插件的完整配置方法、地址格式、TLS 与 keep-alive 调优、启动错误处理策略以及它背后基于源码的连接管理与重连机制。插件概述根据 plugins/outputs/socket_writer/README.md 的定义Socket Writer 插件[[outputs.socket_writer]]的功能是This plugin writes metrics to a network service e.g. via UDP or TCP in one of the supported data formats.它从 Telegrafv1.3.0起可用属于applications应用与network网络类别的插件支持在所有平台上运行all。与专门面向特定服务的输出插件不同它是一个协议无关的通用写入器——只要目标端是一个监听 TCP/UDP/Unix Socket 的服务就可以通过它把 Telegraf 的指标送过去非常适合自建轻量收集端、日志转发代理或自定义协议服务。在plugins/outputs/all/socket_writer.go中可以看到该插件的注册方式它随默认构建自动包含!custom || outputs || outputs.socket_writer并通过import _ github.com/influxdata/telegraf/plugins/outputs/socket_writer完成注册在 socket_writer.go 中调用outputs.Add(socket_writer, ...)将插件名注册进 Telegraf 输出插件体系。全局配置选项与其他插件一样outputs.socket_writer支持 Telegraf 的全局配置与插件级通用配置例如使用namepass、namedrop、tagexclude、tagpass等过滤规则修改指标、标签和字段通过alias创建别名以及配置插件执行顺序order。详见 docs/CONFIGURATION.md#plugins。插件还支持startup_error_behavior设置见下文“启动错误处理策略”小节用于指定插件在启动阶段遇到错误时的行为。完整配置示例以下配置直接取自该插件的官方示例文件 plugins/outputs/socket_writer/sample.conf# Generic socket writer capable of handling multiple socket types. [[outputs.socket_writer]] ## URL to connect to # address tcp://127.0.0.1:8094 # address tcp://example.com:http # address tcp4://127.0.0.1:8094 # address tcp6://127.0.0.1:8094 # address tcp6://[2001:db8::1]:8094 # address udp://127.0.0.1:8094 # address udp4://127.0.0.1:8094 # address udp6://127.0.0.1:8094 # address unix:///tmp/telegraf.sock # address unixgram:///tmp/telegraf.sock # address vsock://cid:port ## 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 ## Period between keep alive probes. ## Only applies to TCP sockets. ## 0 disables keep alive probes. ## Defaults to the OS configuration. # keep_alive_period 5m ## Content encoding for message payloads, can be set to gzip or to ## identity to apply no encoding. ## # content_encoding identity ## Data format to generate. ## Each data format has its own unique set of configuration options, read ## more about them here: ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md # data_format influx下面逐项讲解每个配置参数的含义与底层实现。address目标地址格式address是唯一必需的参数采用scheme://host:port形式的 URL 风格字符串。从 socket_writer.go 的源码可以看到Connect()首先通过strings.SplitN(sw.Address, ://, 2)将地址拆分为协议部分与目标部分因此地址必须包含://分隔符否则会返回invalid address错误。支持的地址格式与说明如下地址格式说明使用场景tcp://127.0.0.1:8094TCP 流式连接常规 TCP 服务如日志代理、自建收集端tcp://example.com:http支持使用服务名代替端口号便于记忆的命名端口tcp4://127.0.0.1:8094强制 IPv4 TCP明确约束协议栈时tcp6://127.0.0.1:8094强制 IPv6 TCPIPv6 环境tcp6://[2001:db8::1]:8094IPv6 字面量地址需用方括号包裹直接连接 IPv6 地址udp://127.0.0.1:8094UDP 数据报对丢包不敏感的指标上报udp4://127.0.0.1:8094强制 IPv4 UDPIPv4 环境udp6://127.0.0.1:8094强制 IPv6 UDPIPv6 环境unix:///tmp/telegraf.sockUnix 域流式套接字本机进程间通信unixgram:///tmp/telegraf.sockUnix 域数据报套接字本机轻量级 IPCvsock://cid:port虚拟机通信套接字仅 Linux宿主机与虚拟机之间通信底层连接实现在源码 socket_writer.go 中Connect()对不同协议采取不同的建连路径vsock走vsock.Dial(uint32(cid), uint32(port), nil)来自github.com/mdlayher/vsock并会校验 CID 与端口号必须是 32 位范围内的数字缺少任一都会返回port and/or CID number missing错误。其他协议在未配置 TLS 时调用net.Dial(spl[0], spl[1])配置了 TLS 时则改用tls.Dial(spl[0], spl[1], tlsCfg)。注意net.Dial的 scheme 参数直接取自地址前缀因此tcp、tcp4、tcp6、udp、udp4、udp6、unix、unixgram都是 Go 标准库net包原生支持的 network 名称。传输类型流式 vs 数据报从测试文件 socket_writer_test.go 可以清晰看到两种传输模型流式streamTCP 与 Unix Socket 走net.Listen/Accept写入的每条指标以换行分隔接收端可用bufio.Scanner逐行读取见testSocketWriterStreamL83-L108。数据报packetUDP 与 Unixgram 走net.ListenPacket/ReadFrom每条指标作为一个独立数据包发送见testSocketWriterPacketL110-L140。这也提醒使用者UDP 是无连接、不保证送达的协议如果要求可靠性应使用 TCP而对吞吐敏感的本地场景unixgram是比 TCP 更轻量的选择。TLS 配置Socket Writer 内嵌了common_tls.ClientConfig见 socket_writer.go因此支持标准的客户端 TLS 配置tls_caCA 证书路径用于校验服务端证书链。tls_cert/tls_key客户端证书与私钥用于双向 TLSmTLS认证。insecure_skip_verify false是否跳过证书链与主机名校验。默认为false即严格校验仅应在受信任的网络环境或自签名证书调试时设为true。从源码可见只要tls_ca、tls_cert、tls_key或insecure_skip_verify任一被设置并成功构建出tls.ConfigConnect()就会改用tls.Dial建立加密连接L88-L92。也就是说只需在配置中声明 TLS 参数即可自动启用加密传输无需额外开关。提示TLS 仅对流式协议TCP有意义UDP 下配置 TLS 参数不会被应用。keep_alive_periodTCP 保活探测keep_alive_period用于设置 TCP 连接的 keep-alive 探测间隔仅对 TCP 套接字生效0表示禁用保活探测默认值为nil即保持操作系统默认配置设置为5m之类的间隔时会启用 TCP keep-alive 并按指定周期发送探测。其底层实现在 socket_writer.go 的setKeepAlive()方法中只有当底层连接是*net.TCPConn时才会生效否则返回“cannot set keep alive on a xxx socket”的错误该错误仅以 Debug 级别日志记录不会中断插件运行。若设置为0则调用SetKeepAlive(false)显式关闭否则依次调用SetKeepAlive(true)与SetKeepAlivePeriod(...)。对长连接场景如对接云端收集网关、经过 NAT 的网络合理的 keep-alive 配置可以及时发现半开连接避免写数据时才发现对端已断开。content_encoding载荷内容编码content_encoding决定发送给对端的数据载荷是否经过压缩编码可选值identity默认不进行任何编码直接发送原始序列化文本。gzip使用 gzip 压缩后再发送可显著降低 UDP 报文大小或 TCP 传输带宽。实现上Connect()通过internal.NewContentEncoder(sw.ContentEncoding)构建编码器socket_writer.go编码器注册逻辑位于 internal/content_coding.go支持gzip与identity空字符串等价于identity两种模式。若传入其他未知值会返回错误。测试 TestSocketWriter_udp_gzip 验证了 gzip 编码在 UDP 路径上的完整工作流。使用时需注意接收端必须能够解压 gzip否则会收到乱码压缩对高冗余文本如 JSON、Line Protocol收益明显。data_format输出数据格式data_format指定指标的序列化格式默认influxInfluxDB Line Protocol。Socket Writer 使用 Telegraf 的通用输出序列化器体系因此支持 docs/DATA_FORMATS_OUTPUT.md 中列出的全部标准输出格式包括InfluxDB Line ProtocolinfluxBinarybinaryCarbon2carbon2CloudEventscloudeventsCSVcsvGraphitegraphiteJSONjsonMessagePackmsgpackPrometheusprometheusPrometheus Remote WriteprometheusremotewriteServiceNow MetricsnowmetricSplunkMetricsplunkmetricTemplatetemplateWavefrontwavefront每种格式都有各自专属的配置选项如 JSON 的json_timestamp_units、Graphite 的模板等可在对应序列化器插件的配置中查看。从源码看插件通过SetSerializer方法注入序列化器socket_writer.go并在Write()中逐条调用sw.serializer.Serialize(m)完成序列化L143-L148因此序列化失败只影响单条指标不会中断整体写入。启动错误处理策略startup_error_behavior与其他插件一致outputs.socket_writer支持startup_error_behavior参数用于控制启动阶段连接目标失败时的行为。可选值如下见 docs/includes/startup_error_behavior.mderror启动失败时 Telegraf 停止并退出。这是默认行为。ignore忽略该插件的启动错误将其禁用但继续处理其他插件。retry启动失败时插件在每个采集/写入周期都会尝试重新启动成功前保持禁用。probe如果可能对插件功能进行探测探测失败则禁用若插件不支持探测则按ignore处理。Socket Writer 对启动错误的支持在源码层面有直接体现Connect()中当建连失败时返回internal.StartupError{Err: sockErr, Retry: true}socket_writer.go标记该错误可重试。测试文件中的TestStartupErrorBehaviorDefault/Error/Ignore/RetryL220-L374则系统验证了四种策略的实际行为例如默认与error策略下目标端口未监听时model.Connect()会返回*internal.StartupErrorignore策略下错误被转换为*internal.FatalError插件被移除retry策略下启动不报错写入返回internal.ErrNotConnected直到监听端就绪后同一写入周期内自动恢复。这组测试非常直观地展示了retry策略的价值当目标服务可能晚于 Telegraf 启动时如容器编排、服务依赖场景设置startup_error_behavior retry可让 Telegraf 免于退出等待目标就绪后自动开始写入。写入与断线重连机制理解Write()的实现有助于判断生产环境中的重连行为。核心逻辑位于 socket_writer.go若Conn为nil上一次写入遇到永久性错误后连接已被关闭会先调用Connect()重新建立连接。对每条指标依次执行序列化 → 内容编码 →Conn.Write(bs)。若写入失败且错误类型为net.Error网络层永久错误则关闭连接并置空Conn返回错误由上层在下一个写入周期重试即自动重连。测试 TestSocketWriter_Write_err 验证了写入失败后Conn被置为nilTestSocketWriter_Write_reconnect 则验证了在连接断开、目标重新监听后下一次Write()能自动重建连接并成功送达数据。此外Write()注释明确标注了“Not parallel safe”非并行安全Telegraf 框架会保证对同一输出实例的写入调用是串行的无需在插件内额外加锁。典型使用场景对接自建指标接收端用一个监听tcp://127.0.0.1:8094的轻量服务接收 Line Protocol前端再用任何支持该格式的时序数据库消费。跨宿主机转发通过tcp6/udp6地址格式将指标送到 IPv6 网络中的收集节点。本地进程间通信使用unix://或unixgram://与同机运行的 Agent、日志管道高效交换数据避免 TCP 协议栈开销。宿主机 ↔ 虚拟机通信Linux 下使用vsock://cid:port直连虚拟机的 vsock 服务。高吞吐传输配合content_encoding gzip压缩载荷降低带宽占用配合data_format json或graphite对接相应协议风格的接收端。关键参考路径插件文档plugins/outputs/socket_writer/README.md插件示例配置plugins/outputs/socket_writer/sample.conf插件核心实现plugins/outputs/socket_writer/socket_writer.go插件测试用例plugins/outputs/socket_writer/socket_writer_test.go插件注册入口plugins/outputs/all/socket_writer.go输出数据格式清单docs/DATA_FORMATS_OUTPUT.md插件通用配置与顺序控制docs/CONFIGURATION.md#plugins【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表