scrapfly-alerting

Scrapfly Alerting

Scrapfly Alerting を使うと、顧客はプロジェクトのメトリクスにしきい値ルールを設定（成功率、ブロック率、エラー数、コスト、レイテンシなど）し、設定可能な期間にわたってルール違反が続いた場合に通知を受け取れます。3 つの呼び出し方法で同じバックエンドを利用します。api.scrapfly.io の REST API、MCP の alert_* ツール、および scrapfly alert CLI サブコマンドです。呼び出し元に合った方法を選んでください。ペイロードの形式、状態遷移、通知チャネルはすべて共通です。

このスキルは、Scrapfly アカウントのアラートを設定する、または既存のアラートを管理するよう依頼された AI エージェントが読むことを想定しています。基本原則は、しきい値を決して推測しないことです。必ず実際のアカウントの動作に基づいて選び、確定する前に履歴と照らし合わせて検証してください。

使用するタイミング

• ユーザーが「X が下がったら知らせて」／「Y が Z を超えたら教えて」と言った場合
• 特定のドメイン、プロジェクト、または製品を監視したい場合
• 既存のアラートを確認したい場合（list、get、ノイズの多いアラートのスヌーズ、メンテナンス期間後のスヌーズ解除など）
• 監視レポートで、現在発火中のアラートを把握したい場合（count-active）

前提条件

• Enterprise プラン（しきい値検出フローが依存する Monitoring API は Enterprise 専用です）。
• 有効な Scrapfly API キー（scp-live-...）。MCP と CLI の各インターフェースでは API キーからプロジェクトのコンテキストを解決します。顧客がデフォルト以外のプロジェクトを明示した場合に限り、--project-uuid／project_uuid を渡してください。

基本のワークフロー

このフローは、3 つすべての呼び出し方法で共通です。順番どおりに実行してください。各ステップの結果を次のステップの根拠にします。

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. アラートを作成する — 2 段階で行います。最初の呼び出しでドライランのペイロードが返され、ユーザーが確認できます。その後、confirm=true を指定して再度呼び出す（または CLI の対話型確認を使う）と確定します。

具体的な例：「スクレイプ成功率が現在のベースラインを大きく下回ったら通知して」→ ベースライン 65.93% を確認 → しきい値を 55% に設定（通常より 10 ポイント低い値）→ プレビューで直近 24 時間の fired_count: 0 を確認 → メールチャネルで作成。エージェントは推測しておらず、すべての数値が実データに基づいています。

パス A — MCP ツール

エージェントが Scrapfly MCP サーバーに接続されている場合、10 個のアラートツールと 2 個の監視ツールですべての機能を利用できます。読み取りツールは副作用がなく、書き込みツールで変更を確定するには 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	読み取り	1 つのサイトのドメイン別内訳です。domain は必須です。group_subdomain を指定すると、サブドメインをまとめて集計します。
alert_metric_families	読み取り	有効な metric_id の値と allowed_dimensions を確認します。alert_create の前に呼び出してください。
alert_list	読み取り	呼び出し元のアラートを、任意のフィルター（state、project_uuid、metric_id）で絞り込んで一覧表示します。
alert_get	読み取り	Webhook チャネル用のアラートごとの HMAC 署名キーを含む、アラートの全情報を取得します。
alert_preview	読み取り	保存前のルールを履歴に対して再生します。alert_create の前に、しきい値の検証に使用してください。
alert_create	書き込み（確認が必要）	新しいアラートを保存します。project_uuid を空のままにすると、プロジェクトが自動的に引き継がれます。
alert_update	書き込み（確認が必要）	フィールドを部分更新します。編集が成功すると、サーバーは sustained_minutes の間、自動的にスヌーズします。
alert_delete	書き込み（確認が必要）	完全に削除します。
alert_snooze	書き込み（確認が必要）	通知をミュートします。minutes:N または until_resolved:true を渡します。
alert_unsnooze	書き込み（確認が必要）	有効なスヌーズを解除します。
alert_test	書き込み（確認が必要）	状態を変更せずに、設定済みの各チャネルへテスト通知を送信します。

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 回発火したルールは、顧客に大量の通知を送ることになります。
• 2 段階での作成は意図された動作です。 最初の呼び出しは 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 ペイロードに 1 対 1 で対応します。

パス 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（1 回だけ通知し、再通知しない）
• 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 があります。

種類	ターゲット	備考
email	RFC 5322 アドレス	Scrapfly のメール送信機能を通じて配信されます。件名にはアラート名と違反値が含まれます。
webhook	HTTPS URL	X-Scrapfly-Signature に HMAC-SHA256 署名を付けて POST します。アラートごとのキーは作成時に生成されます。alert_get または作成レスポンスから確認してください。
inapp	空文字列	ダッシュボードのベルアイコン通知パネルに表示されます。

重複排除レイヤーは、同じ分単位のバケット内で発生する再通知を抑制します。 再通知の間隔（renotify_minutes、デフォルトは 0 で、一度通知した後は再通知しないことを意味します）は、 違反が継続した場合に再通知する頻度を制御し、アラートあたり 1 日 6 回が上限です。

ステートマシン

アラートは次のライフサイクル状態間を遷移します（alert_list は state でフィルタリングします）。

• ok — 違反はありません。
• pending — 違反が検出されましたが、まだ sustained_minutes の間継続していません。
• triggered — 違反が継続し、通知が送信されました。
• recovering — 違反はありませんが、正常なデータが recovery_minutes の間まだ継続していません（デフォルトの 0 は即時復旧を意味します）。
• no_data — 評価ウィンドウの行数が 0 でした。動作は no_data_policy で制御されます。
• snoozed — alert_snooze によってオペレーターが通知をミュートしています。スヌーズ解除時に再開するか、 until_resolved センチネルの場合は次の OK 遷移時に自動解除されます。

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 — チャネルが 0 件、チャネル種別が email|webhook|inapp に含まれない、または test 呼び出しでチャネルに配信できませんでした。
• ERR::ALERT::PROJECT_NOT_FOUND — project_uuid が API キーのプロジェクトと一致しません。多くの場合、エージェントが誤って 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
• スパム対策（重複排除、1 日あたりの上限、再通知）：https://scrapfly.io/docs/alerting/anti-spam