scrapfly-alerting

Scrapfly 告警

Scrapfly 告警允许客户为项目指标设置阈值规则（成功率、拦截率、错误数、成本、延迟……），并在规则在可配置的时间窗口内持续超限时接收通知。三种调用方式共用同一后端：api.scrapfly.io 上的 REST API、MCP alert_* 工具，以及 scrapfly alert CLI 子命令。请选择适合调用方的方式——它们使用相同的负载结构、状态机和通知渠道。

本技能供受托在 Scrapfly 账户中设置告警或管理现有告警的 AI Agent 阅读。黄金法则是：绝不臆造阈值。始终以账户的实际行为为依据，并在提交前根据历史数据进行验证。

适用场景

• 用户说“如果 X 下降就提醒我”／“Y 超过 Z 时告诉我”
• 用户想监控特定域名、项目或产品
• 用户想检查现有告警（list、get、暂缓嘈杂的告警、维护窗口结束后取消暂缓等）
• 监控报告需要了解当前正在触发的告警（count-active）

前提条件

• Enterprise 计划（阈值发现流程依赖的 Monitoring API 仅供 Enterprise 使用）。
• 有效的 Scrapfly API 密钥（scp-live-...）。MCP 和 CLI 接口会根据 api-key 解析项目上下文——仅当客户明确指定非默认项目时，才传入 --project-uuid／project_uuid。

黄金工作流

三种调用方式均使用相同流程。请按顺序执行；每一步都为下一步提供依据。

1. 发现账户基线——获取当前各产品的聚合数据，以了解“正常”情况。
2. （可选）发现各目标的基线——用户指定域名时，获取该域名的细分数据。
3. 列出指标系列——告警注册表会列出合法的 metric_id 值及其 allowed_dimensions。绝不臆造指标 ID；始终从注册表中选择。Unblocker 错误为 scrape.unblocker_errors_per_min。现有告警可能仍使用列表中已不再提供的指标 ID——scrape.asp_errors_per_min 是同一指标重命名前的 ID。这些告警会继续生效并保留原 ID；不要尝试“修复”它们，也不要将已弃用的 ID 用于新告警。
4. 根据历史数据预览阈值——在回溯窗口内重放尚未保存的规则。预览会返回“本应触发”的标记，但不会持久化任何内容。目标是 24 小时内触发 0–2 次：完全不触发表示规则过于宽松，超过约 2 次则表示规则过于敏感。
5. 创建告警——分两步进行：首次调用会返回试运行负载供用户确认，然后再次调用并设置 confirm=true（或通过 CLI 交互式确认）以提交。

具体示例：“当我的抓取成功率明显低于当前基线时提醒我” → 发现基线为 65.93% → 选择 55% 的阈值（比正常值低 10 个百分点）→ 预览显示过去 24 小时内 fired_count: 0 → 使用电子邮件渠道创建告警。Agent 从未凭空猜测；所有数值都来自实际数据。

路径 A — MCP 工具

当 Agent 连接到 Scrapfly MCP 服务时，十个告警工具加上两个监控工具即可覆盖全部功能。读取工具不会产生副作用；写入工具需要 confirm=true 才会提交。

工具	模式	用途
monitoring_get_metrics	read	按产品汇总：选择 product（scrape、screenshot、extraction、crawl、browser）、period（last5m、last1h、last24h、last7d、subscription），还可选择 aggregation（account、project、target）。
monitoring_get_target_metrics	read	查看单个站点按域名细分的数据。必须提供 domain；group_subdomain 可将子域名汇总在一起。
alert_metric_families	read	查找合法的 metric_id 值及其 allowed_dimensions。调用 alert_create 前请先调用此工具。
alert_list	read	列出调用者的告警，可选筛选条件（state、project_uuid、metric_id）。
alert_get	read	获取完整告警记录，包括各告警对应的 webhook 通道 HMAC 签名密钥。
alert_preview	read	根据历史数据回放尚未保存的规则。在调用 alert_create 前，用它验证阈值。
alert_create	write (confirm)	保存新告警。将 project_uuid 留空可继承项目。
alert_update	write (confirm)	修改字段。成功编辑后，服务端会自动静默 sustained_minutes 时长。
alert_delete	write (confirm)	永久删除。
alert_snooze	write (confirm)	静音通知。传入 minutes:N 或 until_resolved:true。
alert_unsnooze	write (confirm)	清除当前静默状态。
alert_test	write (confirm)	在不更改状态的情况下，通过所有已配置的通道发送一条模拟通知。

MCP 示例（将上文的数据驱动工作流转换为工具调用）：

// Step 1 — baseline
{"tool":"monitoring_get_metrics","parameters":{"product":"scrape","period":"last7d","aggregation":["account"]}}

// Step 2 — discover the registry
{"tool":"alert_metric_families","parameters":{}}

// Step 3 — preview the chosen threshold against last-24h history
{"tool":"alert_preview","parameters":{
  "metric_id":"scrape.success_rate",
  "comparator":"lt","threshold":55,
  "sustained_minutes":5,"range_minutes":1440
}}

// Step 4 — dry-run create (no confirm)
{"tool":"alert_create","parameters":{
  "name":"Scrape Success Rate Low",
  "metric_id":"scrape.success_rate",
  "comparator":"lt","threshold":55,
  "sustained_minutes":5,
  "notify_channels":[{"kind":"email","target":"[email protected]"}]
}}

// Step 5 — commit
{"tool":"alert_create","parameters":{ ...same..., "confirm":true }}

关键注意事项

• info_account.account.account_id 不是项目 UUID。 不要将其作为 project_uuid 传入，否则会返回 ERR::ALERT::PROJECT_NOT_FOUND。除非客户明确指定了非默认项目，否则请将 project_uuid 和 project_name 留空；服务端会自动解析 API 密钥当前关联的项目。
• 创建前务必先预览。 alert_preview 使用与实时评估器相同的状态机，因此历史计数准确反映了相同规则在生产环境中的触发情况。若某条规则在过去 24 小时内触发了 15 次，就会向客户发送大量通知。
• 分两步创建是有意设计的。 第一次调用会返回 DRY RUN — POST /alert would be invoked with: { ... }，以便用户在产生通知费用前进行确认。

路径 B — CLI

scrapfly CLI 通过 scrapfly alert ... 子命令提供相同的功能。输出采用标准 {success, product, data|error} JSON 信封格式，因此可以通过管道传递给 jq。

# Discover what's available
scrapfly alert metric-families

# Tune the threshold against history
scrapfly alert preview \
  --metric scrape.success_rate \
  --comparator lt \
  --threshold 95 \
  --sustained-minutes 10 \
  --range-minutes 1440

# Create the alert (channels are repeatable)
scrapfly alert create \
  --name "Scrape Success Rate Low" \
  --metric scrape.success_rate \
  --comparator lt \
  --threshold 95 \
  --sustained-minutes 10 \
  --channel email:[email protected] \
  --channel webhook:https://hooks.example.com/scrapfly

# Or from a version-controlled file (IaC-style)
scrapfly alert create --file ./alerts/success_rate.json

# Manage existing alerts
scrapfly alert list --state triggered
scrapfly alert get <alert-uuid>
scrapfly alert series <alert-uuid> --range-minutes 1440
scrapfly alert update <alert-uuid> --threshold 90
scrapfly alert snooze <alert-uuid> --minutes 30
scrapfly alert snooze <alert-uuid> --until-resolved
scrapfly alert unsnooze <alert-uuid>
scrapfly alert test <alert-uuid>
scrapfly alert delete <alert-uuid>

完整标志参考请参阅 scrapfly alert create --help（或任意子命令加上 --help）。这些标志与下方 REST 负载一一对应。

路径 C — REST API

如果不使用 MCP 或 CLI，可以直接通过 HTTP 调用。端点和负载相同。

POST /alert?key=scp-live-...
Content-Type: application/json

{
  "name": "Scrape Success Rate Low",
  "metric_id": "scrape.success_rate",
  "comparator": "lt",
  "threshold": 95,
  "sustained_minutes": 10,
  "notify_channels": [
    {"kind": "email", "target": "[email protected]"},
    {"kind": "webhook", "target": "https://hooks.example.com/scrapfly"}
  ]
}

发送零值时，服务端会填入以下默认值：

• eval_cadence_seconds：300
• sustained_minutes：指标系列建议的默认值（或 5）
• evaluation_window_m：sustained_minutes
• no_data_policy：ignore
• renotify_minutes：0（仅通知一次，不再重复通知）
• recovery_minutes：0（立即恢复）

其他端点采用相同格式：GET /alert、GET /alert/:uuid、GET /alert/metric-families、GET /alert/count-active、GET /alert/:uuid/series、POST /alert/preview、PUT /alert/:uuid、DELETE /alert/:uuid、POST /alert/:uuid/snooze、POST /alert/:uuid/unsnooze、POST /alert/:uuid/test。

通知渠道

每个渠道都有一个 kind 和一个 target：

Kind	Target	说明
email	RFC 5322 地址	通过 Scrapfly 邮件服务发送。主题包含告警名称和超限值。
webhook	HTTPS URL	通过 POST 请求发送，X-Scrapfly-Signature 中包含 HMAC-SHA256 签名。创建时会为每个告警生成密钥；可从 alert_get 或创建响应中读取。
inapp	空字符串	在仪表板的铃铛图标通知面板中显示。

去重层会抑制落在同一分钟时间段内的重复触发。重新通知频率（renotify_minutes，默认值为 0，表示通知一次后不再重新通知）控制持续超限时的重新通知频率，每个告警每天最多 6 次。

状态机

告警会在以下生命周期状态之间转换（alert_list 可按 state 筛选）：

• ok — 未超限。
• pending — 已观察到超限，但尚未持续达到 sustained_minutes。
• triggered — 超限持续存在；已发送通知。
• recovering — 当前未超限，但尚未持续达到 recovery_minutes 的正常数据时长（默认值为 0，即立即恢复）。
• no_data — 评估窗口内没有数据行。行为由 no_data_policy 控制。
• snoozed — 由操作员通过 alert_snooze 静音。取消静音后恢复，或在下一次转换为 ok 时由 until_resolved 哨兵值自动清除。

count-active 汇总 triggered + pending + recovering，即“需要操作员关注”的状态集合。不要将 snoozed 或 no_data 纳入其中。

常见错误代码

• ERR::ALERT::UNKNOWN_METRIC — metric_id 不在注册表中。请重新调用 alert_metric_families。
• ERR::ALERT::INVALID_DIMENSIONS — 传入的键不在指标系列的 allowed_dimensions 中。
• ERR::ALERT::INVALID_THRESHOLD — 数值非有限，或比较运算符不属于 gt|lt|gte|lte|eq|neq。
• ERR::ALERT::INVALID_SUSTAINED_WINDOW — sustained_minutes 超出 1–1440 范围。
• ERR::ALERT::CHANNEL_UNREACHABLE — 没有任何渠道，或渠道类型不属于 email|webhook|inapp，或 test 调用无法向其渠道发送消息。
• ERR::ALERT::PROJECT_NOT_FOUND — project_uuid 与 API 密钥对应的项目不匹配。最常见的原因是 Agent 错误地在此处传入了 account_id。解决方法：省略该字段，让服务端使用备用值。
• ERR::ALERT::NOT_FOUND — 告警不存在，或不属于你。服务端会将这两种情况合并处理，以防止枚举。不要尝试区分。
• ERR::ALERT::EVAL_TIMEOUT — 预览/序列查询耗时过长。请缩短 range_minutes。
• ERR::ALERT::INTERNAL — 通用服务端故障；请检查响应正文中的 details 字段。

相关技能

• scrapfly-cli — scrapfly alert 子命令附带的 CLI 二进制文件。
• scrapfly-agent-rules — 跨工具通用规则，包括监控→预览→创建流程。
• scrapfly-scraper — 底层抓取产品；scrape.success_rate 等指标 ID 来源于此。

参考

• 概念指南：https://scrapfly.io/docs/alerting/getting-started
• 指标注册表：https://scrapfly.io/docs/alerting/metric-reference
• 状态机：https://scrapfly.io/docs/alerting/state-machine
• Webhook 负载与签名：https://scrapfly.io/docs/alerting/webhook-payload
• 错误参考：https://scrapfly.io/docs/alerting/error-reference
• 反垃圾机制（去重、每日上限、重新通知）：https://scrapfly.io/docs/alerting/anti-spam