sentry-create-alert

创建 Sentry 警报

通过 Sentry 的工作流引擎 API 创建警报。

注意：此 API 目前处于测试版，后续可能会有变更。 它是新监控和警报功能的一部分，可能无法在旧版警报 UI 中查看。

在以下情况下调用此技能

• 用户要求“创建 Sentry 警报”或“设置通知”
• 用户希望在问题符合特定条件时收到邮件或通知
• 用户提到优先级警报、降级警报或工作流自动化
• 用户希望为 Sentry 问题配置 Slack、PagerDuty 或邮件通知

前置条件

• Shell 中可使用 curl
• 具有 alerts:write 范围的 Sentry 组织身份验证令牌（也接受 org:admin 或 org:write）

阶段 1：收集配置

询问用户补充缺失的信息：

详情	必填	示例
组织 slug	是	sentry、my-org
身份验证令牌	是	sntryu_...（需要 alerts:write 范围）
区域	是（默认值：us）	us → us.sentry.io、de → de.sentry.io
警报名称	是	"High Priority De-escalation Alert"
触发事件	是	哪些问题事件会触发工作流
条件	可选	执行动作前的筛选条件
动作类型	是	email、slack 或 pagerduty
动作目标	是	用户邮箱、团队、频道或服务

阶段 2：查询 ID

根据需要使用以下 API 调用将名称解析为 ID。

API="https://{region}.sentry.io/api/0/organizations/{org}"
AUTH="Authorization: Bearer {token}"

# Find user ID by email
curl -s "$API/members/" -H "$AUTH" | python3 -c "
import json,sys
for m in json.load(sys.stdin):
  if m.get('email')=='USER_EMAIL' or m.get('user',{}).get('email')=='USER_EMAIL':
    print(m['user']['id']); break"

# List teams
curl -s "$API/teams/" -H "$AUTH" | python3 -c "
import json,sys
for t in json.load(sys.stdin):
  print(t['id'], t['slug'])"

# List integrations (for Slack/PagerDuty)
curl -s "$API/integrations/" -H "$AUTH" | python3 -c "
import json,sys
for i in json.load(sys.stdin):
  print(i['id'], i['provider']['key'], i['name'])"

阶段 3：构建 Payload

触发事件

选择会触发工作流的问题事件。 使用 logicType: "any-short"（触发器必须始终使用此值）。

类型	触发条件
first_seen_event	创建新问题
regression_event	已解决的问题再次出现
reappeared_event	已归档的问题再次出现
issue_resolved_trigger	问题已解决

筛选条件

执行动作前必须满足的条件。 使用 logicType: "all"、"any-short" 或 "none"。

comparison 字段的类型不固定——其格式取决于条件的 type：

类型	comparison 格式	说明
issue_priority_greater_or_equal	75（裸整数）	优先级 >= 低（25）/中（50）/高（75）
issue_priority_deescalating	true（裸布尔值）	优先级低于峰值
event_frequency_count	{"value": 100, "interval": "1hr"}	时间窗口内的事件数量
event_unique_user_frequency_count	{"value": 50, "interval": "1hr"}	时间窗口内受影响的用户数
tagged_event	{"key": "level", "match": "eq", "value": "error"}	事件标签匹配
assigned_to	{"targetType": "Member", "targetIdentifier": 123}	问题已分配给目标
level	{"level": 40, "match": "gte"}	事件级别（致命 = 50、错误 = 40、警告 = 30）
age_comparison	{"time": "hour", "value": 24, "comparisonType": "older"}	问题时长
issue_category	{"value": 1}	类别（1 = 错误、6 = 反馈、10 = 故障：运行时间和 cron）
issue_occurrences	{"value": 100}	总发生次数

时间间隔选项："1min"、"5min"、"15min"、"1hr"、"1d"、"1w"、"30d"

标签匹配类型："co"（包含）、"nc"（不包含）、"eq"、"ne"、"sw" （以……开头）、"ew"（以……结尾）、"is"（已设置）、"ns"（未设置）

将 conditionResult 设为 false 可反转条件（条件不满足时触发）。

操作

类型	关键配置
email	config.targetType："user" / "team" / "issue_owners"，config.targetIdentifier：<id>
slack	integrationId：<id>，config.targetDisplay："#channel-name"
pagerduty	integrationId：<id>，config.targetDisplay：<service_name>，data.priority："critical"
discord	integrationId：<id>，data.tags：标签列表
msteams	integrationId：<id>，config.targetDisplay：<channel>
opsgenie	integrationId：<id>，data.priority："P1"-"P5"
jira	integrationId：<id>，data：项目/问题配置
github	integrationId：<id>，data：仓库/问题配置

完整载荷结构

{
  "name": "<Alert Name>",
  "enabled": true,
  "environment": null,
  "config": { "frequency": 30 },
  "triggers": {
    "logicType": "any-short",
    "conditions": [
      { "type": "first_seen_event", "comparison": true, "conditionResult": true }
    ],
    "actions": []
  },
  "actionFilters": [{
    "logicType": "all",
    "conditions": [
      { "type": "issue_priority_greater_or_equal", "comparison": 75, "conditionResult": true },
      { "type": "event_frequency_count", "comparison": {"value": 50, "interval": "1hr"}, "conditionResult": true }
    ],
    "actions": [{
      "type": "email",
      "integrationId": null,
      "data": {},
      "config": {
        "targetType": "user",
        "targetIdentifier": "<user_id>",
        "targetDisplay": null
      },
      "status": "active"
    }]
  }]
}

frequency：重复通知的间隔分钟数。 允许的值：0、5、10、30、60、180、720、1440。

结构说明： triggers.actions 始终为 []——操作位于 actionFilters[].actions 中。

阶段 4：创建警报

curl -s -w "\n%{http_code}" -X POST \
  "https://{region}.sentry.io/api/0/organizations/{org}/workflows/" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{payload}'

预期 HTTP 201。响应中包含工作流 id。

阶段 5：验证

确认警报已创建，并提供 UI 链接：

https://{org_slug}.sentry.io/monitors/alerts/{workflow_id}/

如果组织没有 workflow-engine-ui 功能标志，警报会显示在：

https://{org_slug}.sentry.io/alerts/rules/

管理警报

# List all workflows
curl -s "$API/workflows/" -H "$AUTH"

# Get one workflow
curl -s "$API/workflows/{id}/" -H "$AUTH"

# Update a workflow
curl -s -X PUT "$API/workflows/{id}/" -H "$AUTH" -H "Content-Type: application/json" -d '{payload}'

# Delete a workflow
curl -s -X DELETE "$API/workflows/{id}/" -H "$AUTH"
# Expect 204

故障排除

问题	解决方案
401 未授权	令牌需要 alerts:write 范围
403 禁止访问	令牌必须属于目标组织
404 未找到	检查组织 slug 和区域（us 与 de）
400 错误请求	验证载荷 JSON 结构，并检查必填字段
未找到用户 ID	确认邮箱与组织成员的邮箱一致