axiom-alerting

Axiom 告警

在 Axiom 中端到端管理告警：使用通知器进行路由，使用监视器进行检测。

API 概览

基础 URL：https://api.axiom.co/v2/，使用来自 .axiom.toml（项目根目录或 ~/.axiom.toml）的 Bearer 令牌进行身份验证。

监视器（/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. 每次更改后重新检查历史记录。

最佳实践

• 每个通知器配置一个渠道。
• 邮件通知器负载使用 emails（而不是 recipients）。
• 对于嘈杂的信号，优先使用 triggerAfterNPositiveResults/triggerFromNRuns。
• 在监视器查询中显式使用 bin()；避免将 bin_auto() 用于告警逻辑。
• 对于基于指标的监视器，定义时优先使用 mplQuery；API 响应可能同时包含 aplQuery 和 mplQuery。

监视器类型和运算符

监视器类型：

• Threshold
• MatchEvent
• AnomalyDetection

运算符：

• Above
• Below
• AboveOrEqual
• BelowOrEqual
• AboveOrBelow

Monitor 字段参考

核心字段：

• name：易读的 Monitor 名称。
• type：Threshold、MatchEvent 或 AnomalyDetection。
• aplQuery / mplQuery：由 Monitor 执行的查询。
• notifierIds：要通知的 Notifier ID 数组。
• disabled：Monitor 是否已禁用。
• disabledUntil：可选的临时禁用/暂停时间戳。
• description：可选的 Monitor 描述。

阈值和评估字段：

• operator：阈值比较运算符。
• threshold：数值阈值。
• rangeMinutes：查询评估窗口，单位为分钟。
• intervalMinutes：评估间隔，单位为分钟。
• alertOnNoData：无数据时是否触发告警。
• triggerAfterNPositiveResults：触发前所需的肯定评估次数。
• triggerFromNRuns：N-of-M 逻辑所考虑的评估运行总次数。

高级行为字段：

• resolvable：告警是否可以自动解决。
• notifyByGroup：按组键/值结果发送通知。
• notifyEveryRun：每次肯定评估时都发送通知。
• skipResolved：跳过已解决状态的通知。
• secondDelay：容忍数据延迟到达的时间（秒）。

特定类型字段：

• columnName：某些异常/值异常 Monitor 使用的字段。

最简有效 Monitor 示例

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
}

最简有效 Notifier 示例

电子邮件：

{
  "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：

• 原因：令牌缺少所需权限。
• 解决方法：
  • 为 Monitor/Notifier 管理和数据集查询访问创建/分配令牌作用域。
  • 重试：
    • scripts/monitor-list <deployment>

404 Not Found（get/update/delete 时）：

• 原因：Monitor/Notifier ID 错误，或部署/组织错误。
• 解决方法：
  • 确认 .axiom.toml 中的部署。
  • 重新列出对象并使用准确的 ID：
    • scripts/monitor-list <deployment> --json
    • scripts/notifier-list <deployment> --json

400 Bad Request（创建/更新 Notifier 时）：

• 原因：Notifier 载荷结构无效。
• 解决方法：
  • 在 properties 中使用一个 Notifier 通道。
  • 对于电子邮件，使用 emails（而不是 recipients）。
  • 对照已知有效的示例进行验证并重试：
    • scripts/notifier-create <deployment> <json-file>

400 Bad Request（创建/更新 Monitor 时）：

• 原因：Monitor 架构无效、运算符/类型不匹配，或查询字段无效。
• 解决方法：
  • 验证必需字段：name、type、查询字段、计划和 notifierIds。
  • 确认 operator 与 Monitor 类型和阈值逻辑相匹配。
  • 重试：
    • scripts/monitor-create <deployment> <json-file>
    • scripts/monitor-update <deployment> <id> <json-file>

Monitor 已创建但从未触发告警：

• 原因：阈值过于严格、查询窗口错误，或肯定运行次数不足。
• 解决方法：
  • 检查已知活跃时段内的历史记录：
    • scripts/monitor-history <deployment> <id> <startTime> <endTime>
  • 降低阈值或扩大 rangeMinutes。
  • 调整 triggerAfterNPositiveResults/triggerFromNRuns。

告警过多（Monitor 噪声过大）：

• 原因：阈值过低或间隔过短。
• 解决方法：
  • 提高阈值。
  • 增加 triggerAfterNPositiveResults 和/或 triggerFromNRuns。
  • 增大 intervalMinutes 或缩小匹配条件范围。

Notifier 已存在但未送达：

• 原因：目标配置无效（URL/密钥/频道/电子邮件列表），或被目标端拒绝。
• 解决方法：
  • 获取 Notifier 并验证目标字段：
    • scripts/notifier-get <deployment> <id>
  • 使用更正后的属性重新创建/更新 Notifier：
    • scripts/notifier-update <deployment> <id> <json-file>
  • 确认 Monitor 引用了正确的 Notifier ID。