scrapfly-alerting
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseScrapfly Alerting
Scrapfly Alerting
Scrapfly Alerting lets customers attach threshold rules to project
metrics (success rate, block rate, error count, cost, latency, ...) and
receive notifications when a rule sustains a breach over a configurable
window. Three call paths share the same backend: REST API on
, MCP tools, and the CLI
subcommand. Pick whichever fits the caller — the same payload shapes,
same state machine, same notification channels.
api.scrapfly.ioalert_*scrapfly alertThis skill is meant to be read by an AI agent that has been asked to set
up an alert or manage existing alerts on a Scrapfly account. The golden
rule is: never invent a threshold. Always ground the choice in real
account behavior, then validate against history before committing.
Scrapfly Alerting 允许客户为项目指标(成功率、拦截率、错误数、成本、延迟等)附加阈值规则,并在规则持续违反阈值超过可配置时间窗口时接收通知。三条调用路径共用同一个后端:位于 的 REST API、MCP 工具以及 CLI 子命令。可根据调用方选择任意一种路径——它们使用相同的载荷结构、状态机和通知渠道。
api.scrapfly.ioalert_*scrapfly alert此 skill 旨在供 AI Agent 阅读,用于为用户设置告警或管理 Scrapfly 账户中已有的告警。黄金法则是:绝不臆造阈值。始终以真实的账户行为作为阈值选择依据,并在提交前结合历史数据进行验证。
When to use
何时使用
- The user says "alert me if X drops" / "tell me when Y goes above Z"
- The user wants to monitor a specific domain, project, or product
- The user wants to inspect existing alerts (,
list, snooze a noisy alert, unsnooze after a maintenance window, etc.)get - A monitoring report wants to know which alerts are firing right now
()
count-active
- 用户表示“如果 X 下降就提醒我”或“当 Y 超过 Z 时告诉我”
- 用户希望监控特定域名、项目或产品
- 用户希望检查已有告警(、
list、暂时静默一个过于频繁的告警、在维护窗口结束后取消静默等)get - 监控报告需要了解当前正在触发的告警()
count-active
Prerequisites
前置条件
- Enterprise plan (the Monitoring API the threshold-discovery flow depends on is Enterprise-only).
- A valid Scrapfly API key (). The MCP and CLI surfaces act in the project of the api-key, the only project a key reaches alerts in: an alert of another project is listed, created or changed with that project's API key, never by passing its
scp-live-.../--project-uuid.project_uuid
- Enterprise 计划(阈值发现流程所依赖的 Monitoring API 仅限 Enterprise 使用)。
- 有效的 Scrapfly API key()。MCP 和 CLI 接口作用于
scp-live-...所属的项目,而这也是该 key 能够访问告警的唯一项目:要列出、创建或修改其他项目的告警,必须使用该项目的 API key,绝不能通过传入其api-key/--project-uuid来操作。project_uuid
The golden workflow
黄金工作流
This is the same flow used by all three call paths. Run it in order;
each step grounds the next.
- Discover account baseline — fetch the current per-product aggregates so you know what "normal" looks like.
- (Optional) Discover per-target baseline — when the user named a domain, fetch its breakdown.
- List metric families — the Alerting registry tells you the legal
values and their
metric_id. Never invent a metric ID; always pick from the registry. Unblocker errors areallowed_dimensions. An existing alert may still carry a metric ID the listing no longer offers —scrape.unblocker_errors_per_minis the pre-rename ID of that same metric. Those alerts keep working and keep their ID; do not try to "fix" them, and do not reuse a superseded ID for a new alert.scrape.asp_errors_per_min - Preview the threshold against history — replay the unsaved rule over the lookback window. The preview returns "would-have-fired" markers without persisting anything. Aim for 0–2 fires over 24h: silent = rule too lax, more than ~2 = rule too noisy.
- Create the alert — two-step: first call returns a dry-run
payload so the user can confirm, then re-call with (or the CLI's interactive confirm) to commit.
confirm=true
Concrete worked example: "alert me when my scrape success rate drops
noticeably below current baseline" → discover baseline 65.93% → choose
threshold 55% (10pt below normal) → preview shows over
last 24h → create with email channel. The agent never guessed; every
number came from real data.
fired_count: 0三条调用路径均使用相同的流程。请按顺序执行;每一步都为下一步提供可靠依据。
- 发现账户基线——获取当前按产品汇总的数据,以了解“正常”状态。
- (可选)发现按目标划分的基线——当用户指定了域名时,获取其明细数据。
- 列出指标系列——Alerting 注册表会告知合法的 值及其
metric_id。绝不臆造指标 ID;始终从注册表中选择。Unblocker 错误对应的指标为allowed_dimensions。已有告警可能仍使用当前列表不再提供的指标 ID——scrape.unblocker_errors_per_min是同一指标改名前的旧 ID。这些告警仍然有效并保留原 ID;不要尝试“修复”它们,也不要在新告警中复用已被取代的 ID。scrape.asp_errors_per_min - 根据历史数据预览阈值——在回溯窗口上回放尚未保存的规则。预览会返回“本应触发”标记,但不会持久化任何内容。目标是在 24 小时内触发 0–2 次:没有触发意味着规则过于宽松,超过约 2 次则意味着规则过于嘈杂。
- 创建告警——分两步执行:首次调用返回 dry-run 载荷,供用户确认;然后使用 再次调用(或使用 CLI 的交互式确认)以正式提交。
confirm=true
具体示例:“当我的抓取成功率明显低于当前基线时提醒我”→发现基线为 65.93% →选择 55% 作为阈值(比正常值低 10 个百分点)→预览显示过去 24 小时内 →通过电子邮件渠道创建。Agent 从未猜测;每个数字都来自真实数据。
fired_count: 0Path A — MCP tools
路径 A——MCP 工具
When the agent is connected to the Scrapfly MCP server, ten alert tools
plus two monitoring tools cover the full surface. Read tools have no
side-effect; write tools require to commit.
confirm=true| Tool | Mode | Purpose |
|---|---|---|
| read | Per-product aggregates: pick |
| read | Per-domain breakdown for one site. |
| read | Discover legal |
| read | List the alerts of the api-key's project with optional filters ( |
| read | Full alert row including the per-alert HMAC signing key for webhook channels. |
| read | Replay an unsaved rule against history. Use to validate the threshold before |
| write (confirm) | Persist a new alert in the api-key's project. Leave |
| write (confirm) | Patch fields. Server auto-snoozes for |
| write (confirm) | Permanent. |
| write (confirm) | Mute notifications. Pass |
| write (confirm) | Clear active snooze. |
| write (confirm) | Fire a synthetic notification on every configured channel without touching state. |
MCP example (the data-driven workflow from above, expressed as tool
calls):
jsonc
// 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":"ops@example.com"}]
}}
// Step 5 — commit
{"tool":"alert_create","parameters":{ ...same..., "confirm":true }}当 Agent 连接到 Scrapfly MCP server 时,十个告警工具和两个监控工具可覆盖完整功能。读取工具没有副作用;写入工具需要 才会提交。
confirm=true| 工具 | 模式 | 用途 |
|---|---|---|
| 读取 | 按产品汇总的数据:可选择 |
| 读取 | 单个站点的按域名明细。 |
| 读取 | 获取合法的 |
| 读取 | 列出 |
| 读取 | 获取完整告警记录,包括 webhook 渠道使用的每个告警独立的 HMAC 签名密钥。 |
| 读取 | 根据历史数据回放尚未保存的规则。应在 |
| 写入(需确认) | 在 |
| 写入(需确认) | 更新部分字段。成功编辑后,服务端会根据 |
| 写入(需确认) | 永久删除。 |
| 写入(需确认) | 静默通知。传入 |
| 写入(需确认) | 清除当前静默状态。 |
| 写入(需确认) | 在不改变状态的情况下,向每个已配置渠道触发一次合成通知。 |
MCP 示例(将上述数据驱动工作流表达为工具调用):
jsonc
// 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":"ops@example.com"}]
}}
// Step 5 — commit
{"tool":"alert_create","parameters":{ ...same..., "confirm":true }}Critical pitfalls
关键注意事项
- is NOT the project UUID. Do not pass it as
info_account.account.account_id— that returnsproject_uuid. LeaveERR::ALERT::PROJECT_NOT_FOUNDandproject_uuidempty: the server uses the api-key's project, the only one the key reaches. For an alert of another project, use that project's API key.project_name - Always preview before creating. uses the same state machine the live evaluator runs, so the historical count is exactly what production would have produced under the same rule. A rule that fired 15 times in the last 24h will spam the customer.
alert_preview - Two-step create is intentional. The first call returns
so the user can review before paying notification cost.
DRY RUN — POST /alert would be invoked with: { ... }
- 不是项目 UUID。 不要将其作为
info_account.account.account_id传入,否则会返回project_uuid。将ERR::ALERT::PROJECT_NOT_FOUND和project_uuid留空:服务端会使用project_name所属的项目,而这也是该 key 唯一能够访问的项目。要管理其他项目的告警,请使用该项目的 API key。api-key - 创建前务必预览。 使用与实时评估器相同的状态机,因此历史触发次数与生产环境在相同规则下产生的结果完全一致。如果某条规则在过去 24 小时内触发了 15 次,就会向客户发送大量通知。
alert_preview - 两步创建是有意设计的。 首次调用会返回 ,让用户先进行审核,避免在确认前产生通知成本。
DRY RUN — POST /alert would be invoked with: { ... }
Path B — CLI
路径 B——CLI
The CLI exposes the same surface as
subcommands. Output is the standard
JSON envelope so you can pipe it through .
scrapflyscrapfly alert ...{success, product, data|error}jqbash
undefinedscrapflyscrapfly alert ...{success, product, data|error}jqbash
undefinedDiscover what's available
Discover what's available
scrapfly alert metric-families
scrapfly alert metric-families
Tune the threshold against history
Tune the threshold against history
scrapfly alert preview
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--range-minutes 1440
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--range-minutes 1440
scrapfly alert preview
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--range-minutes 1440
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--range-minutes 1440
Create the alert (channels are repeatable)
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:ops@example.com
--channel webhook:https://hooks.example.com/scrapfly
--name "Scrape Success Rate Low"
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--channel email:ops@example.com
--channel webhook:https://hooks.example.com/scrapfly
scrapfly alert create
--name "Scrape Success Rate Low"
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--channel email:ops@example.com
--channel webhook:https://hooks.example.com/scrapfly
--name "Scrape Success Rate Low"
--metric scrape.success_rate
--comparator lt
--threshold 95
--sustained-minutes 10
--channel email:ops@example.com
--channel webhook:https://hooks.example.com/scrapfly
Or from a version-controlled file (IaC-style)
Or from a version-controlled file (IaC-style)
scrapfly alert create --file ./alerts/success_rate.json
scrapfly alert create --file ./alerts/success_rate.json
Manage existing alerts
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>
Full flag reference: `scrapfly alert create --help` (or any subcommand
plus `--help`). The flags map 1:1 to the REST payload below.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 载荷一一对应。Path C — REST API
路径 C——REST API
Direct HTTP if you're not using MCP or the CLI. Same endpoints,
same payloads.
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": "ops@example.com"},
{"kind": "webhook", "target": "https://hooks.example.com/scrapfly"}
]
}Server-side defaults fill in when zero values are sent:
- : 300
eval_cadence_seconds - : the metric family's recommended default (or 5)
sustained_minutes - :
evaluation_window_msustained_minutes - :
no_data_policyignore - : 0 (notify once, never re-notify)
renotify_minutes - : 0 (instant recovery)
recovery_minutes
Other endpoints follow the same shape: , , , , , , , , , , .
GET /alertGET /alert/:uuidGET /alert/metric-familiesGET /alert/count-activeGET /alert/:uuid/seriesPOST /alert/previewPUT /alert/:uuidDELETE /alert/:uuidPOST /alert/:uuid/snoozePOST /alert/:uuid/unsnoozePOST /alert/:uuid/test如果不使用 MCP 或 CLI,可直接通过 HTTP 访问。端点和载荷完全相同。
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": "ops@example.com"},
{"kind": "webhook", "target": "https://hooks.example.com/scrapfly"}
]
}传入零值时,服务端会补齐以下默认值:
- :300
eval_cadence_seconds - :指标系列推荐的默认值(或 5)
sustained_minutes - :
evaluation_window_msustained_minutes - :
no_data_policyignore - :0(仅通知一次,绝不重复通知)
renotify_minutes - :0(立即恢复)
recovery_minutes
其他端点采用相同结构:、、、、、、、、、、。
GET /alertGET /alert/:uuidGET /alert/metric-familiesGET /alert/count-activeGET /alert/:uuid/seriesPOST /alert/previewPUT /alert/:uuidDELETE /alert/:uuidPOST /alert/:uuid/snoozePOST /alert/:uuid/unsnoozePOST /alert/:uuid/testNotification channels
通知渠道
Each channel has a and a :
kindtarget| Kind | Target | Notes |
|---|---|---|
| RFC 5322 address | Delivered via the Scrapfly mailer. Subject carries the alert name and the breach value. |
| HTTPS URL | POST with HMAC-SHA256 signature in |
| empty string | Surfaces in the dashboard's bell-icon notification panel. |
The dedup layer suppresses re-fires that fall in the same minute
bucket. The renotify cadence (, default 0, meaning notify
once and never re-notify) controls
how often a sustained breach re-notifies, capped at 6 / day per alert.
renotify_minutes每个渠道都包含一个 和一个 :
kindtarget| Kind | Target | 说明 |
|---|---|---|
| RFC 5322 地址 | 通过 Scrapfly 邮件服务投递。邮件主题包含告警名称和违规值。 |
| HTTPS URL | 使用 |
| 空字符串 | 显示在仪表板的铃铛图标通知面板中。 |
去重层会抑制同一分钟桶内发生的重复触发。重复通知节奏(,默认值为 0,表示仅通知一次且绝不重复通知)用于控制持续违规时的重复通知频率,每个告警每天最多 6 次。
renotify_minutesState machine
状态机
Alerts transition between these lifecycle states ( filters
on ):
alert_liststate- — no breach.
ok - — breach observed but hasn't yet sustained for
pending.sustained_minutes - — breach sustained; notifications fired.
triggered - — non-breaching but hasn't yet sustained
recoveringof clean data (default 0 = instant recovery).recovery_minutes - — the eval window had zero rows. Behavior controlled by
no_data.no_data_policy - — operator-muted via
snoozed. Resumes on unsnooze or thealert_snoozesentinel auto-clears at the next OK transition.until_resolved
count-activetriggered + pending + recoveringsnoozedno_data告警会在以下生命周期状态之间转换( 可按 筛选):
alert_liststate- ——没有违规。
ok - ——已观察到违规,但尚未持续达到
pending。sustained_minutes - ——违规已持续达到要求,通知已触发。
triggered - ——当前没有违规,但尚未持续达到
recovering的正常数据要求(默认值为 0,即立即恢复)。recovery_minutes - ——评估窗口内没有任何数据行。其行为由
no_data控制。no_data_policy - ——操作员通过
snoozed手动静默。取消静默后恢复;或者当进入下一次 OK 状态转换时,由alert_snooze哨兵值自动清除。until_resolved
count-activetriggered + pending + recoveringsnoozedno_dataCommon error codes
常见错误代码
- —
ERR::ALERT::UNKNOWN_METRICnot in the registry. Re-callmetric_id.alert_metric_families - — passed a key that isn't in the metric family's
ERR::ALERT::INVALID_DIMENSIONS.allowed_dimensions - — non-finite number, or comparator not in
ERR::ALERT::INVALID_THRESHOLD.gt|lt|gte|lte|eq|neq - —
ERR::ALERT::INVALID_SUSTAINED_WINDOWoutside 1–1440.sustained_minutes - — zero channels OR channel kind not in
ERR::ALERT::CHANNEL_UNREACHABLEOR aemail|webhook|inappcall couldn't deliver to its channel.test - —
ERR::ALERT::PROJECT_NOT_FOUNDis not the api-key's project: the agent passedproject_uuidby mistake, or another project of the account, which a key never reaches. Fix: omit the field, and use the other project's API key for its alerts.account_id - — alert doesn't exist OR isn't yours. The server collapses both cases to prevent enumeration. Don't try to distinguish.
ERR::ALERT::NOT_FOUND - — the preview/series query took too long. Reduce
ERR::ALERT::EVAL_TIMEOUT.range_minutes - — generic server-side failure; check the response body's
ERR::ALERT::INTERNALfield.details
- ——
ERR::ALERT::UNKNOWN_METRIC不在注册表中。重新调用metric_id。alert_metric_families - ——传入了不在该指标系列
ERR::ALERT::INVALID_DIMENSIONS中的键。allowed_dimensions - ——数值为非有限数,或 comparator 不在
ERR::ALERT::INVALID_THRESHOLD范围内。gt|lt|gte|lte|eq|neq - ——
ERR::ALERT::INVALID_SUSTAINED_WINDOW不在 1–1440 范围内。sustained_minutes - ——渠道数为零,或渠道 kind 不在
ERR::ALERT::CHANNEL_UNREACHABLE范围内,或email|webhook|inapp调用无法向相应渠道投递。test - ——
ERR::ALERT::PROJECT_NOT_FOUND不是project_uuid所属的项目:Agent 可能误传了api-key,也可能传入了账户中的其他项目,而 key 无法访问这些项目。修复方法:省略该字段,并为对应告警使用其他项目的 API key。account_id - ——告警不存在或不属于当前用户。服务端将两种情况合并处理,以防止枚举。不要尝试区分二者。
ERR::ALERT::NOT_FOUND - ——预览或序列查询耗时过长。请减小
ERR::ALERT::EVAL_TIMEOUT。range_minutes - ——通用服务端故障;请检查响应正文中的
ERR::ALERT::INTERNAL字段。details
Related skills
相关 skill
- — the CLI binary the
scrapfly-clisubcommand ships with.scrapfly alert - — cross-tool golden rules including the monitoring→preview→create flow.
scrapfly-agent-rules - — the underlying scrape product; metric IDs like
scrapfly-scrapercome from there.scrape.success_rate
- ——随
scrapfly-cli子命令一起提供的 CLI 二进制文件。scrapfly alert - ——包含监控→预览→创建流程等跨工具黄金法则。
scrapfly-agent-rules - ——底层抓取产品;
scrapfly-scraper等指标 ID 来自该产品。scrape.success_rate
Reference
参考
- Concept guide: https://scrapfly.io/docs/alerting/getting-started
- Metric registry: https://scrapfly.io/docs/alerting/metric-reference
- State machine: https://scrapfly.io/docs/alerting/state-machine
- Webhook payload + signing: https://scrapfly.io/docs/alerting/webhook-payload
- Error reference: https://scrapfly.io/docs/alerting/error-reference
- Anti-spam (dedup, daily cap, renotify): https://scrapfly.io/docs/alerting/anti-spam
- 概念指南: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