---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - alerts
  - monitoring
topic: LangSmith Smith API Alerts 阈值、变化规则与通知安全
sources:
  - https://docs.langchain.com/langsmith/smith-api/alert_rules/create-an-alert-rule
  - https://docs.langchain.com/langsmith/smith-api/alert_rules/delete-an-alert-rule
  - https://docs.langchain.com/langsmith/smith-api/alert_rules/get-an-alert-rule
  - https://docs.langchain.com/langsmith/smith-api/alert_rules/test-an-alert-action-to-determine-if-configuration-is-valid
  - https://docs.langchain.com/langsmith/smith-api/alert_rules/update-an-alert-rule
last_verified: 2026-08-11
---

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

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

## 端点和响应

| 能力 | 方法与路径 | 成功 |
|---|---|---|
| 创建 | `POST /api/v1/platform/alerts/{session_id}` | 201，rule + actions |
| 读取 | `GET /api/v1/platform/alerts/{session_id}/{alert_rule_id}` | 200 |
| 更新 | `PATCH /api/v1/platform/alerts/{session_id}/{alert_rule_id}` | 200 |
| 删除 | `DELETE /api/v1/platform/alerts/{session_id}/{alert_rule_id}` | 200 |
| 测试 action | `POST /api/v1/platform/alerts/{session_id}/test` | 200，通知已发 |

创建可返 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 会撤销已发通知。