Telegraf webhooks 输入插件：Filestack Webhook 事件采集配置与源码解析

本文以 Telegraf inputs.webhooks 服务插件中的 Filestack 子模块为主线，讲清如何把 Filestack 的 Webhook 指到 Telegraf 服务、事件到 metric 的映射规则（action 标签、id 字段），并结合插件源码与测试用例解析请求处理链路、鉴权、时间戳来源以及“视频转码事件被排除”这一限制的底层原因，读完即可在环境中配置并验证该插件。

一、插件定位：webhooks 服务输入中的一个子监听器

Filestack 采集能力并不是一个独立的输入插件，而是 Telegraf webhooks 服务输入插件（service input）内置的多个 Webhook 监听器之一。webhooks 插件在 webhooks.go 中定义，其 Start 方法会启动一个 HTTP 服务器监听 service_address（默认 :1619），并用 gorilla/mux 路由将配置中声明的各个子模块（Artifactory、Filestack、GitHub、Mandrill、Papertrail、Particle、Rollbar）依次注册为不同路径的 POST 处理器。

从源码结构看，availableWebhooks 通过反射遍历 Webhooks 结构体字段，把实现 Webhook 接口且非 nil 的字段自动注册到路由上——这意味着只有在你配置文件中显式声明了 [inputs.webhooks.filestack] 表时，/filestack 路由才会被挂载。

作为服务输入插件，它有两个使用特点（见 plugins/inputs/webhooks/README.md）：

• 全局或插件级 interval 设置不适用，指标在事件到达时立即生成；
• --test、--test-wait、--once 等 CLI 参数可能不会为该插件产生输出，验证时应使用真实 POST 请求。

二、配置步骤：把 Filestack Webhook 指向 Telegraf

原始插件文档（filestack README）给出的配置流程如下：

1. 登录 Filestack 官方控制台，选中你的应用，进入 Credentials > Webhooks 页面；
2. 将 Webhook 回调 URL 设置为 http://<my_ip>:1619/filestack（<my_ip> 替换为运行 Telegraf 的主机 IP，1619 是 webhooks 插件默认端口，/filestack 是子插件默认路径）；
3. 点击 Add 保存。

对应的 Telegraf 侧配置（摘自官方样例 sample.conf）：

# A Webhooks Event collector
[[inputs.webhooks]]
  ## Address and port to host Webhook listener on
  service_address = ":1619"

  ## Maximum duration before timing out read of the request
  # read_timeout = "10s"
  ## Maximum duration before timing out write of the response
  # write_timeout = "10s"

  [inputs.webhooks.filestack]
    path = "/filestack"

    ## HTTP basic auth
    #username = ""
    #password = ""

参数说明：

配置项	默认值	说明
service_address	:1619	Webhook 监听地址与端口，Filestack 回调 URL 的端口由此决定
read_timeout	10s	读取请求的最大时长。从源码看，webhooks.go 中当配置值小于 1 秒时会强制回落到 defaultReadTimeout = 10 * time.Second
write_timeout	10s	写响应的最大时长，回退逻辑同上（defaultWriteTimeout）
path（filestack 子表）	/filestack	子监听器在 mux 路由上注册的 URL 路径，必须与 Filestack 后台配置的 URL 一致
username / password	空	可选的 HTTP Basic 鉴权凭据，启用后 Filestack 回调必须携带相同凭据

需要说明的是，read_timeout / write_timeout 实际作用于整个 webhooks HTTP 服务器（http.Server 的超时字段），而非 Filestack 子插件单独控制。

三、事件到 metric 的映射规则

原始文档明确给出了采集范围与输出结构：

• 限制：采集所有 Filestack 事件，但视频转码（video conversions）事件除外；
• 每条事件都会记录原始的 timestamp（作为 metric 时间戳）、action 和 id；
• Tags：action = event.action（字符串）；
• Fields：id = event.id（字符串）。

这一映射在源码 filestack_webhooks_events.go 中可以直接印证。事件结构体只解析了回调 JSON 中的三个字段：

type filestackEvent struct {
    Action    string `json:"action"`
    TimeStamp int64  `json:"timestamp"`
    ID        int    `json:"id"`
}

func (fe *filestackEvent) tags() map[string]string {
    return map[string]string{"action": fe.Action}
}

func (fe *filestackEvent) fields() map[string]interface{} {
    return map[string]interface{}{"id": strconv.Itoa(fe.ID)}
}

由此得到两个值得注意的实现细节：

1. 字段类型：JSON 中的 id 是数值型（如 100946），但写入 metric 时经过 strconv.Itoa 转换为字符串存入字段，这与 README 中 id 为 string 的描述一致。也就是说 Filestack 回调中其他字段（如 text.url、text.filename 等）虽然会随 JSON 一起送达，但当前实现并不采集；
2. 时间戳来源：metric 的时间戳不是 Telegraf 收到请求的时刻，而是事件载荷里的 timestamp（Unix 秒），即事件发生时间，可避免传输与处理延迟造成的时间漂移。

四、请求处理链路与错误语义

Filestack 子插件的核心处理逻辑位于 filestack_webhooks.go，完整链路为：

POST /filestack
  → Register 将 handler 绑定到 mux 路由（仅 POST 方法）
  → eventHandler:
      1. fs.Verify(r) 校验 Basic Auth（若配置了 username/password），失败返回 401
      2. io.ReadAll(r.Body) 读取请求体，失败返回 400
      3. json.Unmarshal 解析为 filestackEvent，失败返回 400
      4. acc.AddFields("filestack_webhooks", fields, tags, time.Unix(event.TimeStamp, 0))
      5. 返回 200

对应的 metric 名称固定为 filestack_webhooks。Webhook 结构体内嵌了 plugins/common/auth 提供的 auth.BasicAuth，鉴权是否生效取决于配置中是否设置了 username/password。

测试用例 filestack_webhooks_test.go 验证了上述全部行为：

• TestDialogEvent：投递 dialog_open.json（action: "fp.dialog", id: 102），断言返回 200 且生成标签 action=fp.dialog、字段 id="102" 的 filestack_webhooks 指标；
• TestUploadEvent：投递 upload.json（action: "fp.upload", id: 100946），同样断言 200 与对应字段；
• TestParseError：投递空请求体，断言返回 400（JSON 解析失败分支）。

五、为什么视频转码事件会被排除

README 中的“Limitations”说明排除了视频转码事件。结合测试 TestVideoConversionEvent 可以定位原因：它投递的样例载荷 video_conversion.json 与其余事件结构不同——其 timestamp 是 JSON 字符串（"1453850583"），且没有 action 和数值型 id 字段；而 filestackEvent 要求 timestamp 解析为 int64，因此 json.Unmarshal 直接报错，处理器按第 3 步逻辑返回 400，测试也据此断言状态码为 400。从源码结构看，这不是刻意的业务过滤，而是转码回调的载荷格式与解析器不兼容导致解析失败，所以这类事件天然落不了库。如果你的使用场景涉及视频转码监控，需要自行扩展事件解析（例如将 timestamp 放宽为可接受字符串的形式），或评估该类事件是否必要。

六、验证清单

配置完成后，可以按以下步骤验证链路：

1. 启动 Telegraf，日志中出现 Started the webhooks service on :1619（由 webhooks.go 的 Start 打印），以及 Filestack 子插件的 Started the webhooks_filestack on /filestack；
2. 手动模拟 Filestack 回调：curl -X POST http://<my_ip>:1619/filestack -H 'Content-Type: application/json' -d '{"action":"fp.upload","timestamp":1443444905,"id":100946}'，预期返回 200；
3. 若配置了 Basic 鉴权，则回调需附带凭据，否则返回 401；
4. 在输出端查询 filestack_webhooks 指标，确认 action 标签与 id 字段符合预期。

适用前提与限制小结：该子插件属于 webhooks 服务输入插件的一部分，依赖 Telegraf 常驻运行以暴露 HTTP 端口；仅采集事件中的 action 与 id 两个维度，回调中的其余业务字段不入库；视频转码类事件因载荷格式不同而被 400 拒绝。以上行为均可在 plugins/inputs/webhooks/filestack/ 目录下的源码与测试数据中逐一对照验证。