Telegraf papertrail Webhook 输入插件：将 Papertrail 日志回调转为指标的完整解析

Telegraf 的 inputs.webhooks 服务插件内置了 Papertrail Webhook 监听器，可将 Papertrail 的 Saved Search 回调（事件回调与计数回调）实时转换为 InfluxDB 行协议格式的 papertrail 指标。本文基于插件文档 README 与源码 papertrail_webhooks.go，完整梳理其事件模型、指标字段映射规则、HTTP 请求约束与认证配置，帮助你理解如何在日志监控链路中把 Papertrail 告警事件落地为可查询、可聚合的时序指标。

所属插件与整体架构

Papertrail Webhook 并非独立的 input 插件，而是 <a href="https://link.gitcode.com/i/427b497bdb516b125a1f2eb400254a45" target="_blank">[inputs.webhooks]] 服务输入下的一个子监听器。从 [webhooks.go 可以看到，Webhooks 结构体持有 Papertrail *papertrail.Webhook 字段（toml 键为 papertrail），插件启动时通过 mux.Router 将各子 Webhook 注册到统一的 HTTP 服务上。

父插件的关键行为（见 Start 方法）：

• service_address 指定监听地址与端口，默认 :1619；
• read_timeout / write_timeout 控制请求读取与响应写出的超时，未显式配置或小于 1s 时使用默认的 10s；
• 只有配置了 [inputs.webhooks.papertrail] 表（非 nil）时，availableWebhooks() 才会通过反射把它注册到路由上，因此不需要 Papertrail 时可以不配置该子表。

配置方式

完整的插件配置位于 sample.conf。启用 Papertrail Webhook 的最小配置如下：

[[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.papertrail]
    path = "/papertrail"

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

配置要点：

• path：Papertrail 回调请求到达的 URL 路径，需与 Papertrail 后台配置的 Webhook 回调地址一致；
• username / password：可选的 HTTP Basic 认证，防止未授权请求写入指标。Webhook 结构体内嵌了 auth.BasicAuth（见 papertrail_webhooks.go），eventHandler 中在处理请求前先调用 pt.Verify(r)，认证失败直接返回 401 Unauthorized。

该插件属于 service input：不受 interval 采集周期控制，--test、--once 等 CLI 选项也不会产生输出，指标由外部回调事件驱动产生。

请求格式约束

Papertrail 发出的 Webhook 请求有严格的格式要求，eventHandler（源码第 30-97 行）按以下顺序校验：

1. Content-Type 必须为 application/x-www-form-urlencoded，否则返回 415 Unsupported Media Type；
2. 若配置了 Basic 认证，请求必须携带合法凭据，否则 401；
3. 表单中必须存在 payload 字段且非空，否则 400 Bad Request；
4. payload 的值必须是合法 JSON 并能解析为 payload 结构体（含 events、counts、saved_search、max_id、min_id 字段），否则 400。

这些校验路径均有对应的单元测试覆盖，见 papertrail_test.go 中的 TestWrongContentType、TestMissingPayload、TestPayloadNotJSON、TestPayloadInvalidJSON。

事件回调（event-based callback）的指标映射

当 payload 中包含 events 数组时，按 event 结构体 逐个事件转换为一个 point，转换规则与文档完全一致：

• 时间戳取事件的 received_at；
• 每个 point 带 count 字段，固定为 1，表示事件发生了一次；
• 事件的 hostname 转为 host 标签；
• payload 中 saved_search.name 转为 event 标签；
• saved_search.id 作为 search_id 字段；
• 查看该事件的 Papertrail 链接由 saved_search.html_search_url 拼接 ?centered_on_id=<id> 生成，作为 url 字段；
• 其余事件数据直接转为字段：id、source_ip、source_name、source_id、program、severity、facility、message。

转换后的行协议示例（与文档一致）：

papertrail,host=myserver.example.com,event=saved_search_name count=1i,source_name="abc",program="CROND",severity="Info",source_id=2i,message="message body",source_ip="208.75.57.121",id=7711561783320576i,facility="Cron",url="https://papertrailapp.com/searches/42?centered_on_id=7711561783320576",search_id=42i 1453248892000000000

源码中有两处值得注意的实现细节：

• 注释明确指出 "Duplicate event timestamps will overwrite each other"，即同一时间戳下的重复事件在下游可能相互覆盖，高并发事件流需留意这一语义；
• url 字段的拼接格式为 %s?centered_on_id=%d，其中 %s 是 saved_search 的 html_search_url，保证从指标可以直接跳回 Papertrail 定位原始事件。

TestEventPayload 测试用双事件样例 payload（papertrail_test.go）验证了上述字段映射，包括 host 标签取 hostname（而非 source_name）、url 的拼接结果等。

计数回调（count-based callback）的指标映射

当 payload 不包含 events 而包含 counts 数组时，按 count 结构体 处理：每个 count 对象的 timeseries 是一个"unix epoch → 计数"的映射，插件对其中每个时间片生成一个 point：

• 时间戳取 timeseries 键对应的 unix epoch（time.Unix(ts, 0)）；
• count 字段直接取该时间片的计数值（而非固定 1）；
• count 对象的 source_name 转为 host 标签；
• saved_search.name 同样作为 event 标签。

生成的行协议示例：

papertrail,host=myserver.example.com,event=saved_search_name count=3i 1453248892000000000

TestCountPayload 测试以 timeseries 为 {"1453248895": 5} 与 {"1453248927": 3} 的两条 count 样例验证了该路径。如果 payload 中 events 与 counts 均为空，则返回 400 Bad Request（见 源码第 91-94 行）。

端到端验证

测试文件 papertrail_test.go 提供了可直接复用的两段样例 payload，可用于本地联调时模拟 Papertrail 的 POST 请求：

# 事件回调样例：payload 为 URL-encoded 的 JSON 表单字段
curl -X POST http://localhost:1619/papertrail \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'payload={"events":[{"id":7711561783320576,"received_at":"2011-05-18T20:30:02-07:00","source_ip":"208.75.57.121","source_name":"abc","source_id":2,"hostname":"abc","program":"CROND","severity":"Info","facility":"Cron","message":"message body"}],"saved_search":{"id":42,"name":"Important stuff","html_search_url":"https://papertrailapp.com/searches/42"}}'

预期响应 200 OK，且 InfluxDB 中出现 host=abc、event=Important stuff、count=1i 的 papertrail point。

小结

Papertrail Webhook 是 Telegraf inputs.webhooks 服务插件家族中的一员（同族还包括 Artifactory、Filestack、Github、Mandrill、Particle、Rollbar，见 webhooks README）。其核心能力是：

回调类型	触发条件	时间戳来源	count 字段	额外字段
event-based	payload 含 events	received_at	固定 1	id、source_ip、source_name、source_id、program、severity、facility、message、url、search_id
count-based	payload 仅含 counts	timeseries 键（unix epoch）	时间片计数值	无

配置上只需在 [[inputs.webhooks]] 下添加 [inputs.webhooks.papertrail] 子表、设置 path（可选 Basic 认证），并让 Papertrail 将 Saved Search 的 Webhook 指向该地址即可。若需深入了解其他子 Webhook 或全局超时参数，可继续查阅 sample.conf 与 webhooks.go。