Telegraf 的 Sensu Go 输出插件通过 HTTP Events API 上报指标的完整指南【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的outputs.sensu插件负责将采集、处理、聚合后的指标通过 Sensu Go 的 HTTP Events API 写入 Sensu 监控平台使 Sensu 能够基于这些指标数据执行告警、事件处理与指标存储。阅读本文后你将掌握该插件的双 API 模式Backend API 与 Agent API、完整的 TOML 配置方法、API Key 的签发流程以及插件底层的事件结构与写入流程从而在生产环境中正确接入 Sensu Go。插件概览与适用场景outputs.sensu是 Telegraf 官方输出插件之一通过 Sensu Go 的 HTTP Events API 将指标作为Sensu Event事件写入目标后端。根据 plugins/outputs/sensu/README.md 的标注引入版本Telegraf v1.18.0 起提供插件类别applications面向应用类监控场景支持平台all全平台无操作系统限制。插件在源码中通过outputs.Add(sensu, ...)完成注册见 plugins/outputs/sensu/sensu.go 的init()函数并在 plugins/outputs/all/sensu.go 中以import _ github.com/influxdata/telegraf/plugins/outputs/sensu的形式被默认构建引入。也就是说使用默认方式编译的 Telegraf 二进制已经内置该插件只需要在配置文件中声明[[outputs.sensu]]即可启用。典型的应用场景是你在 Sensu Go 中统一管理告警与事件流希望把 Telegraf 采集到的系统/应用指标例如 CPU、内存、业务自定义指标一并送入 Sensu由 Sensu 的 handler如 InfluxDB、Elasticsearch负责存储或进一步处理。该插件正是连接 Telegraf 数据管道与 Sensu Go 事件模型的桥梁。工作原理Backend API 与 Agent API 双模式Sensu Go 提供了两条可接收指标事件的 HTTP 通道该插件均支持模式配置项自动拼接的 API 路径用途Backend APIbackend_api_url/api/core/v2/namespaces/:entity_namespace/events直接写入 Sensu Backend需要 API Key 认证Agent APIagent_api_url/events写入本机 Sensu Agent由 Agent 转发到 Backend从源码 sensu.go 的setEndpointURL()方法可以看到端点的解析优先级与完整逻辑若配置了backend_api_url则使用该地址并拼接/api/core/v2/namespaces/namespace/events其中 namespace 取entity.namespace的值未配置时默认为default否则若配置了agent_api_url则使用该地址并拼接/events若两者都未提供或值解析后为空插件会回退到默认的 Agent API 地址http://127.0.0.1:3031路径同样为/events。关于优先级README 中有明确说明当backend_api_url、agent_api_url与api_key同时设置时插件始终优先使用backend_api_url。这一行为同样体现在setEndpointURL()中——BackendAPIURL的判断先于AgentAPIURL。对应的单元测试位于 sensu_test.go 的TestResolveEventEndpointUrl覆盖了四种组合仅配置agent_api_url→http://127.0.0.1:3031/events同时配置 Agent 与 Backend → 使用 Backend 且 namespace 为默认值default配置 Backend 且显式声明entity.namespace test-namespace→/api/core/v2/namespaces/test-namespace/eventsagent_api_url为空字符串 → 回退到默认地址。完整配置示例以下是插件完整可用的配置与 plugins/outputs/sensu/sample.conf 及 README 中的示例保持一致# Send aggregate metrics to Sensu Monitor [[outputs.sensu]] ## BACKEND API URL is the Sensu Backend API root URL to send metrics to ## (protocol, host, and port only). The output plugin will automatically ## append the corresponding backend API path ## /api/core/v2/namespaces/:entity_namespace/events/:entity_name/:check_name). ## ## Backend Events API reference: ## https://docs.sensu.io/sensu-go/latest/api/events/ ## ## AGENT API URL is the Sensu Agent API root URL to send metrics to ## (protocol, host, and port only). The output plugin will automatically ## append the correspeonding agent API path (/events). ## ## Agent API Events API reference: ## https://docs.sensu.io/sensu-go/latest/api/events/ ## ## NOTE: if backend_api_url and agent_api_url and api_key are set, the output ## plugin will use backend_api_url. If backend_api_url and agent_api_url are ## not provided, the output plugin will default to use an agent_api_url of ## http://127.0.0.1:3031 ## # backend_api_url http://127.0.0.1:8080 # agent_api_url http://127.0.0.1:3031 ## API KEY is the Sensu Backend API token ## Generate a new API token via: ## ## $ sensuctl cluster-role create telegraf --verb create --resource events,entities ## $ sensuctl cluster-role-binding create telegraf --cluster-role telegraf --group telegraf ## $ sensuctl user create telegraf --group telegraf --password REDACTED ## $ sensuctl api-key grant telegraf ## ## For more information on Sensu RBAC profiles API tokens, please visit: ## - https://docs.sensu.io/sensu-go/latest/reference/rbac/ ## - https://docs.sensu.io/sensu-go/latest/reference/apikeys/ ## # api_key ${SENSU_API_KEY} ## 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 ## Timeout for HTTP message # timeout 5s ## HTTP Content-Encoding for write request body, can be set to gzip to ## compress body or identity to apply no encoding. # content_encoding identity ## NOTE: Due to the way TOML is parsed, tables must be at the END of the ## plugin definition, otherwise additional config options are read as part of ## the table ## Sensu Event details ## ## Below are the event details to be sent to Sensu. The main portions of the ## event are the check, entity, and metrics specifications. For more information ## on Sensu events and its components, please visit: ## - Events - https://docs.sensu.io/sensu-go/latest/reference/events ## - Checks - https://docs.sensu.io/sensu-go/latest/reference/checks ## - Entities - https://docs.sensu.io/sensu-go/latest/reference/entities ## - Metrics - https://docs.sensu.io/sensu-go/latest/reference/events#metrics ## ## Check specification ## The check name is the name to give the Sensu check associated with the event ## created. This maps to check.metadata.name in the event. [outputs.sensu.check] name telegraf ## Entity specification ## Configure the entity name and namespace, if necessary. This will be part of ## the entity.metadata in the event. ## ## NOTE: if the output plugin is configured to send events to a ## backend_api_url and entity_name is not set, the value returned by ## os.Hostname() will be used; if the output plugin is configured to send ## events to an agent_api_url, entity_name and entity_namespace are not used. # [outputs.sensu.entity] # name server-01 # namespace default ## Metrics specification ## Configure the tags for the metrics that are sent as part of the Sensu event # [outputs.sensu.tags] # source telegraf ## Configure the handler(s) for processing the provided metrics # [outputs.sensu.metrics] # handlers [influxdb,elasticsearch]核心参数详解1. 端点地址backend_api_url与agent_api_urlbackend_api_urlSensu Backend API 的根地址仅需协议、主机与端口三部分例如http://127.0.0.1:8080插件会自动拼接/api/core/v2/namespaces/namespace/events。该模式下写入的是 Backend 的 core/v2 Events API。agent_api_urlSensu Agent API 的根地址插件自动拼接/events。Agent 默认监听3031端口因此该模式无需暴露 Backend 端口更贴近本机 Agent 上报的部署形态。两者都未配置时插件默认使用http://127.0.0.1:3031对应源码中的defaultURL常量见 sensu.go。注意agent_api_url模式不使用实体名与命名空间详见下文 entity 小节。2. API Keyapi_key当使用 Backend API 时必须提供api_key。这一点在源码Init()中有强校验如果配置了backend_api_url但没有api_key插件会直接返回错误backend_api_url [...] specified, but no API Key provided导致插件初始化失败。README 给出了通过sensuctl签发 API Key 的完整流程四步# 1. 创建 cluster-role授予对 events 与 entities 资源的 create 权限 $ sensuctl cluster-role create telegraf --verb create --resource events,entities # 2. 创建 cluster-role-binding将 telegraf 角色绑定到 telegraf 组 $ sensuctl cluster-role-binding create telegraf --cluster-role telegraf --group telegraf # 3. 创建用户并加入 telegraf 组 $ sensuctl user create telegraf --group telegraf --password REDACTED # 4. 为该用户签发 API Key $ sensuctl api-key grant telegraf签名完成后将得到的 Key 填入api_key。示例配置使用${SENSU_API_KEY}环境变量引用即通过 Telegraf 的环境变量替换机制详见 docs/CONFIGURATION.md 中关于环境变量的说明避免明文落盘。HTTP 请求发出时插件会将该 Key 放入Authorization请求头格式为Key api_key。3. TLS 配置插件内嵌 Telegraf 通用的 TLSClientConfig源码中tls.ClientConfig匿名内嵌支持以下选项配置项默认值说明tls_ca空CA 证书路径用于校验服务端证书链tls_cert空客户端证书路径mTLS 双向认证时使用tls_key空客户端私钥路径insecure_skip_verifyfalse设为true时跳过证书链与主机名校验仅建议在测试环境使用在Connect()阶段插件通过s.ClientConfig.TLSConfig()构建*http.Transport的TLSClientConfig并连同超时配置一起组装成http.Client见 sensu.go 的createClient()。4. 请求超时timeoutHTTP 请求超时时间默认5s源码中的defaultClientTimeout。若 Sensu 后端处理较慢或网络链路较长可适当调大例如timeout 10s。5. 内容编码content_encoding请求体的 HTTP Content-Encoding可选identity不压缩或gzipgzip 压缩默认identity。源码Init()会对该值做白名单校验传入其他值会报错unsupported content_encoding [...] specified。当指标量很大时开启gzip可显著降低网络传输开销写入时插件会将请求头Content-Encoding设置为gzip并借助internal.CompressWithGzipinternal/internal.go对流式数据进行压缩。6. 关于 TOML 表顺序的注意事项README 特别提醒由于 TOML 的解析方式[outputs.sensu.check]、[outputs.sensu.entity]等子表必须放在整个插件定义的最后否则后续的配置项会被错误地解析为子表的一部分。实际使用中应保持示例配置的书写顺序。事件结构check / entity / tags / metrics插件将 Telegraf 指标封装为一个 Sensu Event事件体包含entity、check、metrics与timestamp四个主要部分对应源码中的outputEvent结构体。事件体以 JSON 序列化后通过 HTTP POST 发送。Check检查规格[outputs.sensu.check] name telegrafcheck.name映射到事件的check.metadata.name即与该事件关联的 Sensu Check 名称。源码getCheck()中该字段是必填项——若未配置插件会返回missing check name错误并拒绝写入。此外插件会为 Check 自动填充status: 0始终标记为 OK因为 Telegraf 上报的是指标数据而非告警状态output: Telegraf agent processed N metricsN 为本次写入的指标点数issuedUnix 时间戳output_metric_handlers与 metrics 部分的 handlers 相同。Entity实体规格[outputs.sensu.entity] name server-01 namespace defaultentity.name与entity.namespace会进入事件的entity.metadata。行为规则如下使用Backend API时若未显式配置name插件会调用os.Hostname()取本机主机名作为实体名见 sensu.go 的setEntity()使用Agent API时entity.name与entity.namespace均不会被使用由 Agent 侧负责实体归属此时插件只发送空的 entity 对象。Tags标签规格[outputs.sensu.tags] source telegraftags是一个自由键值映射会被附加到每一个发送的指标点上用于标注数据来源等公共维度。结合源码看插件在组装指标点时会先追加配置的 tags再追加指标自身的 tags。Metrics指标规格与 Handlers[outputs.sensu.metrics] handlers [influxdb, elasticsearch]metrics.handlers指定处理这些指标数据的 Sensu handler 列表例如持久化到 InfluxDB、Elasticsearch 的 handler 名称对应事件metrics.handlers字段。未配置时 handlers 为空数组指标仍会随事件上报只是没有显式指定处理者。指标写入流程源码级剖析从 sensu.go 的Write()方法可以还原完整的写入流水线遍历指标构建点集对每个 Telegraf 指标将其全部 tags 与配置 tags 合并为outputTag列表然后遍历FieldList()把每个数值字段转换成一个outputMetric点。字段值转 float64getFloat()支持float64/float32/int64/int32/int/uint64/uint32/uint共 8 种数值类型到float64的转换遇到其他类型如字符串、布尔值返回math.NaN()。特殊值处理由于 JSON 不支持Inf与NaN正无穷 → 替换为math.MaxFloat64负无穷 → 替换为-math.MaxFloat64NaN→ 直接跳过该点不写入。以上情况均输出 Debug 级别日志便于排查。指标点命名点的名称采用metric.Name() . fieldKey的拼接形式例如指标cpu的字段value会生成名为cpu.value的点时间戳取指标时间的Unix()秒值。封装事件encodeToJSON()组装outputEvent其中metrics.points为全部指标点、metrics.handlers来自配置、事件级timestamp取当前时间。发送请求writeMetrics()使用 HTTP POST请求头包括Content-Type: application/json; charsetutf-8源码常量defaultContentTypeUser-Agent由internal.ProductToken()见 internal/internal.go生成格式类似Telegraf/version Go/go-version配置了 API Key 时附带Authorization: Key api_key开启 gzip 时附带Content-Encoding: gzip。响应处理成功以 HTTP201 Created为准Sensu 创建事件的语义非 2xx 时若状态码为 4xx客户端错误记录 Debug 日志但不返回错误避免因后端拒绝数据导致 Telegraf 输出端不断重试若为其他状态码如 5xx 服务端错误返回包含状态码的错误触发 Telegraf 的重试机制。测试验证与质量保障仓库为插件提供了较完整的单元测试plugins/outputs/sensu/sensu_test.go主要覆盖端点解析TestResolveEventEndpointUrl验证 Agent/Backend 模式下的路径拼接、namespace 默认值与自定义、空 URL 回退逻辑连接与写入TestConnectAndWrite使用httptest启动模拟服务端校验请求 URL、Authorization头格式Key a0b1c2d3-...、事件体中 check 名、entity 名、metrics 非空、handlers 包含配置值以及指标点名称/值与配置 tags 是否正确落位数值转换TestGetFloat逐一验证 8 种数值类型的转换结果以及非数值类型的NaN返回值。这些测试不仅验证了配置到行为的映射关系也为二次开发或排查接入问题提供了可参考的行为基准。与其他配置体系的衔接和所有 Telegraf 插件一样outputs.sensu同样支持全局/插件级配置能力例如利用namepass、namedrop、tagpass等过滤指标使用alias重命名插件实例以及通过处理器顺序控制数据流。具体说明见 docs/CONFIGURATION.md。小结outputs.sensu插件以简洁的配置在 Telegraf 与 Sensu Go 之间建立了标准化的指标通道通过 Backend/Agent 双 API 适配不同部署拓扑通过事件模型entity/check/metrics与 Sensu 的 RBAC、handlers 机制无缝集成并在源码层面妥善处理了端点解析、TLS、压缩、特殊浮点值等工程细节。接入时只需重点确认三点选用哪种 API 模式、是否已为 Backend 模式签发 API Key、事件结构中的 check 名是否按需配置即可稳定运行。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考