scrapfly-alerting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scrapfly 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
api.scrapfly.io
, MCP
alert_*
tools, and the
scrapfly alert
CLI subcommand. Pick whichever fits the caller — the same payload shapes, same state machine, same notification channels.
This 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 允许客户为项目指标(成功率、拦截率、错误数、成本、延迟等)附加阈值规则,并在规则持续违反阈值超过可配置时间窗口时接收通知。三条调用路径共用同一个后端:位于
api.scrapfly.io
的 REST API、MCP
alert_*
工具以及
scrapfly alert
CLI 子命令。可根据调用方选择任意一种路径——它们使用相同的载荷结构、状态机和通知渠道。
此 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
    ,
    get
    , snooze a noisy alert, unsnooze after a maintenance window, etc.)
  • 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 (
    scp-live-...
    ). 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
    --project-uuid
    /
    project_uuid
    .
  • Enterprise 计划(阈值发现流程所依赖的 Monitoring API 仅限 Enterprise 使用)。
  • 有效的 Scrapfly API key(
    scp-live-...
    )。MCP 和 CLI 接口作用于
    api-key
    所属的项目,而这也是该 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.
  1. Discover account baseline — fetch the current per-product aggregates so you know what "normal" looks like.
  2. (Optional) Discover per-target baseline — when the user named a domain, fetch its breakdown.
  3. List metric families — the Alerting registry tells you the legal
    metric_id
    values and their
    allowed_dimensions
    . Never invent a metric ID; always pick from the registry. Unblocker errors are
    scrape.unblocker_errors_per_min
    . An existing alert may still carry a metric ID the listing no longer offers —
    scrape.asp_errors_per_min
    is 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.
  4. 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.
  5. Create the alert — two-step: first call returns a dry-run payload so the user can confirm, then re-call with
    confirm=true
    (or the CLI's interactive confirm) to commit.
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
fired_count: 0
over last 24h → create with email channel. The agent never guessed; every number came from real data.
三条调用路径均使用相同的流程。请按顺序执行;每一步都为下一步提供可靠依据。
  1. 发现账户基线——获取当前按产品汇总的数据,以了解“正常”状态。
  2. (可选)发现按目标划分的基线——当用户指定了域名时,获取其明细数据。
  3. 列出指标系列——Alerting 注册表会告知合法的
    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. 创建告警——分两步执行:首次调用返回 dry-run 载荷,供用户确认;然后使用
    confirm=true
    再次调用(或使用 CLI 的交互式确认)以正式提交。
具体示例:“当我的抓取成功率明显低于当前基线时提醒我”→发现基线为 65.93% →选择 55% 作为阈值(比正常值低 10 个百分点)→预览显示过去 24 小时内
fired_count: 0
→通过电子邮件渠道创建。Agent 从未猜测;每个数字都来自真实数据。

Path 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
confirm=true
to commit.
ToolModePurpose
monitoring_get_metrics
readPer-product aggregates: pick
product
(scrape, screenshot, extraction, crawl, browser),
period
(
last5m
,
last1h
,
last24h
,
last7d
,
subscription
), and optionally
aggregation
(
account
,
project
,
target
).
monitoring_get_target_metrics
readPer-domain breakdown for one site.
domain
is required;
group_subdomain
rolls subdomains together.
alert_metric_families
readDiscover legal
metric_id
values + their
allowed_dimensions
. Call before
alert_create
.
alert_list
readList the alerts of the api-key's project with optional filters (
state
,
metric_id
).
alert_get
readFull alert row including the per-alert HMAC signing key for webhook channels.
alert_preview
readReplay an unsaved rule against history. Use to validate the threshold before
alert_create
.
alert_create
write (confirm)Persist a new alert in the api-key's project. Leave
project_uuid
empty.
alert_update
write (confirm)Patch fields. Server auto-snoozes for
sustained_minutes
after a successful edit.
alert_delete
write (confirm)Permanent.
alert_snooze
write (confirm)Mute notifications. Pass
minutes:N
OR
until_resolved:true
.
alert_unsnooze
write (confirm)Clear active snooze.
alert_test
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
才会提交。
工具模式用途
monitoring_get_metrics
读取按产品汇总的数据:可选择
product
(scrape、screenshot、extraction、crawl、browser)、
period
(
last5m
、
last1h
、
last24h
、
last7d
、
subscription
),以及可选的
aggregation
(
account
、
project
、
target
)。
monitoring_get_target_metrics
读取单个站点的按域名明细。
domain
为必填项;
group_subdomain
会将子域名汇总在一起。
alert_metric_families
读取获取合法的
metric_id
值及其
allowed_dimensions
。调用
alert_create
前必须先调用此工具。
alert_list
读取列出
api-key
所属项目的告警,可使用可选筛选条件(
state
、
metric_id
)。
alert_get
读取获取完整告警记录,包括 webhook 渠道使用的每个告警独立的 HMAC 签名密钥。
alert_preview
读取根据历史数据回放尚未保存的规则。应在
alert_create
前使用它验证阈值。
alert_create
写入(需确认)在
api-key
所属项目中持久化新告警。将
project_uuid
留空。
alert_update
写入(需确认)更新部分字段。成功编辑后,服务端会根据
sustained_minutes
自动静默告警。
alert_delete
写入(需确认)永久删除。
alert_snooze
写入(需确认)静默通知。传入
minutes:N
或
until_resolved:true
。
alert_unsnooze
写入(需确认)清除当前静默状态。
alert_test
写入(需确认)在不改变状态的情况下,向每个已配置渠道触发一次合成通知。
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

关键注意事项

  • info_account.account.account_id
    is NOT the project UUID.
    Do not pass it as
    project_uuid
    — that returns
    ERR::ALERT::PROJECT_NOT_FOUND
    . Leave
    project_uuid
    and
    project_name
    empty: 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.
  • Always preview before creating.
    alert_preview
    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.
  • Two-step create is intentional. The first call returns
    DRY RUN — POST /alert would be invoked with: { ... }
    so the user can review before paying notification cost.
  • info_account.account.account_id
    不是项目 UUID。
    不要将其作为
    project_uuid
    传入,否则会返回
    ERR::ALERT::PROJECT_NOT_FOUND
    。将
    project_uuid
    和
    project_name
    留空:服务端会使用
    api-key
    所属的项目,而这也是该 key 唯一能够访问的项目。要管理其他项目的告警,请使用该项目的 API key。
  • 创建前务必预览。
    alert_preview
    使用与实时评估器相同的状态机,因此历史触发次数与生产环境在相同规则下产生的结果完全一致。如果某条规则在过去 24 小时内触发了 15 次,就会向客户发送大量通知。
  • 两步创建是有意设计的。 首次调用会返回
    DRY RUN — POST /alert would be invoked with: { ... }
    ,让用户先进行审核,避免在确认前产生通知成本。

Path B — CLI

路径 B——CLI

The
scrapfly
CLI exposes the same surface as
scrapfly alert ...
subcommands. Output is the standard
{success, product, data|error}
JSON envelope so you can pipe it through
jq
.
bash
undefined
scrapfly
CLI 通过
scrapfly alert ...
子命令提供与上述路径相同的功能。输出采用标准的
{success, product, data|error}
JSON envelope,因此可以通过管道传给
jq
。
bash
undefined

Discover 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
scrapfly alert preview
--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
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

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:
  • eval_cadence_seconds
    : 300
  • sustained_minutes
    : the metric family's recommended default (or 5)
  • evaluation_window_m
    :
    sustained_minutes
  • no_data_policy
    :
    ignore
  • renotify_minutes
    : 0 (notify once, never re-notify)
  • recovery_minutes
    : 0 (instant recovery)
Other endpoints follow the same shape:
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
.
如果不使用 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"}
  ]
}
传入零值时,服务端会补齐以下默认值:
  • 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
。

Notification channels

通知渠道

Each channel has a
kind
and a
target
:
KindTargetNotes
email
RFC 5322 addressDelivered via the Scrapfly mailer. Subject carries the alert name and the breach value.
webhook
HTTPS URLPOST with HMAC-SHA256 signature in
X-Scrapfly-Signature
. Per-alert key generated on create; read it from
alert_get
or the create response.
inapp
empty stringSurfaces in the dashboard's bell-icon notification panel.
The dedup layer suppresses re-fires that fall in the same minute bucket. The renotify cadence (
renotify_minutes
, default 0, meaning notify once and never re-notify) controls how often a sustained breach re-notifies, capped at 6 / day per alert.
每个渠道都包含一个
kind
和一个
target
:
KindTarget说明
email
RFC 5322 地址通过 Scrapfly 邮件服务投递。邮件主题包含告警名称和违规值。
webhook
HTTPS URL使用
X-Scrapfly-Signature
携带 HMAC-SHA256 签名进行 POST。创建时会生成每个告警独立的密钥;可从
alert_get
或创建响应中读取。
inapp
空字符串显示在仪表板的铃铛图标通知面板中。
去重层会抑制同一分钟桶内发生的重复触发。重复通知节奏(
renotify_minutes
,默认值为 0,表示仅通知一次且绝不重复通知)用于控制持续违规时的重复通知频率,每个告警每天最多 6 次。

State machine

状态机

Alerts transition between these lifecycle states (
alert_list
filters on
state
):
  • ok
    — no breach.
  • pending
    — breach observed but hasn't yet sustained for
    sustained_minutes
    .
  • triggered
    — breach sustained; notifications fired.
  • recovering
    — non-breaching but hasn't yet sustained
    recovery_minutes
    of clean data (default 0 = instant recovery).
  • no_data
    — the eval window had zero rows. Behavior controlled by
    no_data_policy
    .
  • snoozed
    — operator-muted via
    alert_snooze
    . Resumes on unsnooze or the
    until_resolved
    sentinel auto-clears at the next OK transition.
count-active
sums
triggered + pending + recovering
— the "needs operator attention" set. Don't include
snoozed
or
no_data
.
告警会在以下生命周期状态之间转换(
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
。

Common error codes

常见错误代码

  • ERR::ALERT::UNKNOWN_METRIC
    —
    metric_id
    not in the registry. Re-call
    alert_metric_families
    .
  • ERR::ALERT::INVALID_DIMENSIONS
    — passed a key that isn't in the metric family's
    allowed_dimensions
    .
  • ERR::ALERT::INVALID_THRESHOLD
    — non-finite number, or comparator not in
    gt|lt|gte|lte|eq|neq
    .
  • ERR::ALERT::INVALID_SUSTAINED_WINDOW
    —
    sustained_minutes
    outside 1–1440.
  • ERR::ALERT::CHANNEL_UNREACHABLE
    — zero channels OR channel kind not in
    email|webhook|inapp
    OR a
    test
    call couldn't deliver to its channel.
  • ERR::ALERT::PROJECT_NOT_FOUND
    —
    project_uuid
    is not the api-key's project: the agent passed
    account_id
    by 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.
  • ERR::ALERT::NOT_FOUND
    — alert doesn't exist OR isn't yours. The server collapses both cases to prevent enumeration. Don't try to distinguish.
  • ERR::ALERT::EVAL_TIMEOUT
    — the preview/series query took too long. Reduce
    range_minutes
    .
  • ERR::ALERT::INTERNAL
    — generic server-side failure; check the response body's
    details
    field.
  • ERR::ALERT::UNKNOWN_METRIC
    ——
    metric_id
    不在注册表中。重新调用
    alert_metric_families
    。
  • ERR::ALERT::INVALID_DIMENSIONS
    ——传入了不在该指标系列
    allowed_dimensions
    中的键。
  • ERR::ALERT::INVALID_THRESHOLD
    ——数值为非有限数,或 comparator 不在
    gt|lt|gte|lte|eq|neq
    范围内。
  • ERR::ALERT::INVALID_SUSTAINED_WINDOW
    ——
    sustained_minutes
    不在 1–1440 范围内。
  • ERR::ALERT::CHANNEL_UNREACHABLE
    ——渠道数为零,或渠道 kind 不在
    email|webhook|inapp
    范围内,或
    test
    调用无法向相应渠道投递。
  • ERR::ALERT::PROJECT_NOT_FOUND
    ——
    project_uuid
    不是
    api-key
    所属的项目:Agent 可能误传了
    account_id
    ,也可能传入了账户中的其他项目,而 key 无法访问这些项目。修复方法:省略该字段,并为对应告警使用其他项目的 API key。
  • ERR::ALERT::NOT_FOUND
    ——告警不存在或不属于当前用户。服务端将两种情况合并处理,以防止枚举。不要尝试区分二者。
  • ERR::ALERT::EVAL_TIMEOUT
    ——预览或序列查询耗时过长。请减小
    range_minutes
    。
  • ERR::ALERT::INTERNAL
    ——通用服务端故障;请检查响应正文中的
    details
    字段。

Related skills

相关 skill

  • scrapfly-cli
    — the CLI binary the
    scrapfly alert
    subcommand ships with.
  • scrapfly-agent-rules
    — cross-tool golden rules including the monitoring→preview→create flow.
  • scrapfly-scraper
    — the underlying scrape product; metric IDs like
    scrape.success_rate
    come from there.
  • scrapfly-cli
    ——随
    scrapfly alert
    子命令一起提供的 CLI 二进制文件。
  • scrapfly-agent-rules
    ——包含监控→预览→创建流程等跨工具黄金法则。
  • scrapfly-scraper
    ——底层抓取产品;
    scrape.success_rate
    等指标 ID 来自该产品。

Reference

参考