Alerts：阈值、变化规则与通知安全

Alert Rule 以 tracing project（session_id）为作用域，将指标聚合条件与一组通知 action 绑定。测试 action 会真正向配置的收件人发送通知，不是纯本地 dry-run。

端点和响应

创建可返 429 Alert Rule Limit Reached。全组还明确 400/403/5xx，读/改/删有 404。当前组内没有 list 端点，业务端要保存创建响应中的 ID，或通过已验证的其他控制面查询，不要猜测路径。

Rule 模型

Rule 必填：

• name、description；
• type=threshold|change；
• aggregation=avg|sum|pct；
• attribute=latency|error_count|feedback_score|run_latency|run_count|total_cost；
• operator=gte|lte|gt|lt；
• window_minutes，限 1–60。

还可带 filter、denominator_filter、threshold、threshold_multiplier、threshold_window_minutes。Schema 未用 oneOf 强制 threshold/change 各自需要哪些字段，客户端应按 rule type 建立严格条件校验，并用线上同等时间桶的历史数据回放验证阈值。

pct 聚合时 denominator filter 会影响分母；必须处理分母为 0、迟到 Trace、空窗口和时区。费用/延迟指标要明确单位，不将文档中未定义的默认单位当事实。

Action 与出站安全

Action 必填 target 和不透明 config，target 支持 pagerduty|webhook|dynatrace|slack。由于 config 是自由对象，控制面必须按 target 做白名单 schema，不接受任意 URL/header。Webhook/Dynatrace 要防 SSRF：禁私网/元数据 IP、固定 DNS/重定向策略、限制端口和响应体，使用密钥引用而不是明文凭据。

通知消费端需幂等 event ID、签名、短超时、有界重试和 dead-letter queue。报警引擎需 cooldown/dedup/escalation，否则滚动窗口会对同一故障形成通知风暴。

Test 端点存在 OpenAPI 契约缺口

当前 operation path 是 /api/v1/platform/alerts/{session_id}/test，但 parameters 又声明一个 required path 参数 alert_rule_id，路径模板中却没有这个 placeholder，同时也没有 request body。这是已验证的文档/OpenAPI 不一致，不能据此推断服务器实际传参方式。

不把此端点直接纳入自动化 SDK/生产发布；先用目标部署的 contract test 验证精确 URL/参数，并确认测试会发真通知。在受控测试收件人/非生产 channel 上验证，为测试事件加明显标识，避免触发真实 on-call。

变更流程

新 Rule 先在预生产或高阈值/受控 channel 上创建，用历史窗口评估命中率，再逐步切换收件人。更新请求要求完整 actions + rule，不要把 PATCH 当任意子集；先读快照、生成差异、保存回滚版本。删除前先从通知平台核对无在途事件；文档没有承诺删 Rule 会撤销已发通知。