axiom-alerting

Axiom のアラート

Axiom のアラートをエンドツーエンドで管理します。通知先のルーティングには通知先を、検知にはモニターを使用します。

API の概要

ベース URL：https://api.axiom.co/v2/。Bearer トークン認証には、.axiom.toml（プロジェクトのルートまたは ~/.axiom.toml）を使用します。

モニター（/v2/monitors）

操作	メソッド	パス
一覧表示	GET	/v2/monitors
取得	GET	/v2/monitors/{id}
履歴	GET	/v2/monitors/{id}/history
作成	POST	/v2/monitors
更新	PUT	/v2/monitors/{id}
削除	DELETE	/v2/monitors/{id}

通知先（/v2/notifiers）

操作	メソッド	パス
一覧表示	GET	/v2/notifiers
取得	GET	/v2/notifiers/{id}
作成	POST	/v2/notifiers
更新	PUT	/v2/notifiers/{id}
削除	DELETE	/v2/notifiers/{id}

前提条件

1. scripts/setup を実行します。
2. .axiom.toml にデプロイメントが設定されていることを確認します。

[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"

スクリプト

コア：

• scripts/axiom-api <deploy> <method> <path> [body]

モニターのスクリプト：

• scripts/monitor-list <deployment> [--json]
• scripts/monitor-get <deployment> <id>
• scripts/monitor-history <deployment> <id> <startTime> <endTime>
• scripts/monitor-create <deployment> <json-file>
• scripts/monitor-update <deployment> <id> <json-file>
• scripts/monitor-delete <deployment> <id>

通知先のスクリプト：

• scripts/notifier-list <deployment> [--json]
• scripts/notifier-get <deployment> <id>
• scripts/notifier-create <deployment> <json-file>
• scripts/notifier-update <deployment> <id> <json-file>
• scripts/notifier-delete <deployment> <id>

推奨ワークフロー

1. 最初に通知先を作成します。
2. モニターを作成し、notifierIds を設定します。
3. monitor-history を使用して、モニターの動作を検証します。
4. モニターのしきい値とスケジュールを調整します。

ワークフロー：エンドツーエンドのアラート

1. scripts/setup を実行します。
2. scripts/notifier-list <deployment> で既存の通知先を一覧表示し、適切なものがあれば再利用します。
3. 適切な通知先がない場合は、scripts/notifier-create で作成します。
4. notifierIds を設定して、モニターを作成または更新します。
5. scripts/monitor-history <deployment> <id> <startTime> <endTime> で検証します。
6. 動作が過剰に反応する、または反応しない場合は、threshold、rangeMinutes、intervalMinutes、N-of-M トリガーフィールドを調整します。
7. 変更するたびに履歴を再確認します。

ベストプラクティス

• 通知先ごとにチャネルを 1 つ設定します。
• メール通知先のペイロードには、recipients ではなく emails を使用します。
• ノイズの多いシグナルには、triggerAfterNPositiveResults／triggerFromNRuns を優先して使用します。
• モニタークエリでは明示的な bin() を使用し、アラートロジックでは bin_auto() を避けます。
• メトリクスを基にしたモニターでは、定義に mplQuery を優先して使用します。API の応答には aplQuery と mplQuery の両方が含まれる場合があります。

モニターの種類と演算子

モニターの種類：

• Threshold
• MatchEvent
• AnomalyDetection

演算子：

• Above
• Below
• AboveOrEqual
• BelowOrEqual
• AboveOrBelow

モニターのフィールドリファレンス

基本フィールド：

• name：人が読みやすいモニター名です。
• type：Threshold、MatchEvent、またはAnomalyDetectionです。
• aplQuery / mplQuery：モニターによって評価されるクエリです。
• notifierIds：通知先の通知機能 ID の配列です。
• disabled：モニターが無効かどうかを示します。
• disabledUntil：一時的な無効化／スヌーズに使用する任意のタイムスタンプです。
• description：任意のモニターの説明です。

しきい値と評価に関するフィールド：

• operator：しきい値の比較演算子です。
• threshold：数値のしきい値です。
• rangeMinutes：クエリの評価期間（分）です。
• intervalMinutes：評価間隔（分）です。
• alertOnNoData：データがない場合にアラートを発報するかどうかを示します。
• triggerAfterNPositiveResults：アラート発報に必要な、条件を満たす評価の回数です。
• triggerFromNRuns：N-of-M ロジックで考慮する評価実行の合計回数です。

高度な動作に関するフィールド：

• resolvable：アラートを自動的に解決できるかどうかを示します。
• notifyByGroup：グループキー／値ごとに通知します。
• notifyEveryRun：条件を満たす評価のたびに通知します。
• skipResolved：解決通知の送信をスキップします。
• secondDelay：データの到着遅延を許容するための遅延時間（秒）です。

タイプ固有のフィールド：

• columnName：一部の異常検知／値異常検知モニターで使用するフィールドです。

最小限の有効なモニターの例

Threshold：

{
  "name": "High Error Count",
  "type": "Threshold",
  "aplQuery": "['logs'] | where status >= 500 | summarize count()",
  "operator": "Above",
  "threshold": 100,
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "triggerAfterNPositiveResults": 2,
  "triggerFromNRuns": 3,
  "disabled": false
}

MatchEvent：

{
  "name": "Error Event Match",
  "type": "MatchEvent",
  "aplQuery": "['logs'] | where level == 'error'",
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "disabled": false
}

AnomalyDetection：

{
  "name": "CPU Anomaly",
  "type": "AnomalyDetection",
  "aplQuery": "['metrics'] | summarize avg(cpu_usage)",
  "columnName": "cpu_usage",
  "operator": "AboveOrBelow",
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "disabled": false
}

最小限の有効な通知機能の例

メール：

{
  "name": "Oncall Email",
  "properties": {
    "email": {
      "emails": ["[email protected]"]
    }
  }
}

Slack：

{
  "name": "Oncall Slack",
  "properties": {
    "slack": {
      "slackUrl": "https://hooks.slack.com/services/T.../B.../XXX"
    }
  }
}

カスタム Webhook：

{
  "name": "Oncall Custom Webhook",
  "properties": {
    "customWebhook": {
      "url": "https://api.example.com/alerts",
      "body": "{\"action\":\"{{.Action}}\",\"monitorID\":\"{{.MonitorID}}\"}"
    }
  }
}

トラブルシューティング

401 Unauthorized：

• 原因：トークンが無効か、期限切れです。
• 対処方法：
  • ~/.axiom.toml のトークンを確認します。
  • scripts/setup を再実行して、次のコマンドを試します。
    • scripts/notifier-list <deployment>

403 Forbidden：

• 原因：トークンに必要な権限がありません。
• 対処方法：
  • モニター／通知機能の管理とデータセットのクエリアクセスに必要なスコープを持つトークンを作成／割り当てます。
  • 次のコマンドを試します。
    • scripts/monitor-list <deployment>

get／update／delete で404 Not Foundが発生する場合：

• 原因：モニター／通知機能 ID、またはデプロイメント／組織が間違っています。
• 対処方法：
  • .axiom.toml のデプロイメントを確認します。
  • オブジェクトを再度一覧表示し、正確な ID を使用します。
    • scripts/monitor-list <deployment> --json
    • scripts/notifier-list <deployment> --json

通知機能の作成／更新で400 Bad Requestが発生する場合：

• 原因：通知機能のペイロードの形式が無効です。
• 対処方法：
  • properties 内に通知チャネルを 1 つだけ指定します。
  • メールの場合は、recipients ではなくemailsを使用します。
  • 正常な動作が確認されている例を使って検証し、次のコマンドを試します。
    • scripts/notifier-create <deployment> <json-file>

モニターの作成／更新で400 Bad Requestが発生する場合：

• 原因：モニタースキーマ、演算子とタイプの不一致、またはクエリフィールドが無効です。
• 対処方法：
  • name、type、クエリフィールド、スケジュール、notifierIds などの必須フィールドを検証します。
  • operator がモニターのタイプとしきい値のロジックに合っていることを確認します。
  • 次のコマンドを試します。
    • scripts/monitor-create <deployment> <json-file>
    • scripts/monitor-update <deployment> <id> <json-file>

モニターは作成されたものの、アラートが一度も発報されない場合：

• 原因：しきい値が厳しすぎる、クエリ期間が適切でない、または条件を満たす実行回数が不足しています。
• 対処方法：
  • 稼働が確認されている期間の履歴を調べます。
    • scripts/monitor-history <deployment> <id> <startTime> <endTime>
  • しきい値を下げるか、rangeMinutes を広げます。
  • triggerAfterNPositiveResults／triggerFromNRuns を調整します。

アラートが多すぎる（モニターが過剰に通知する）場合：

• 原因：しきい値が低すぎる、または間隔が短すぎます。
• 対処方法：
  • しきい値を上げます。
  • triggerAfterNPositiveResults および／またはtriggerFromNRuns を増やします。
  • intervalMinutes を増やすか、一致条件を絞り込みます。

通知機能は存在するものの、通知が届かない場合：

• 原因：送信先の設定（URL／キー／チャネル／メールリスト）が無効か、送信先側で拒否されています。
• 対処方法：
  • 通知機能を取得し、送信先のフィールドを確認します。
    • scripts/notifier-get <deployment> <id>
  • プロパティを修正して通知機能を再作成／更新します。
    • scripts/notifier-update <deployment> <id> <json-file>
  • モニターが正しい通知機能 ID を参照していることを確認します。