LangSmith 中的警报

• 具有管理员访问权限的有效 PagerDuty 账户
• PagerDuty 中适当的服务级权限

​

1. 在 PagerDuty 中创建服务

1. 登录 PagerDuty 账户
2. 进入 Services → Service Directory
3. 点击 + New Service
4. 填写以下字段：
   • Name：提供描述性名称（例如“LangSmith Monitoring”）
   • Description：添加有关受监控应用的详细信息
   • Escalation Policy：选择适当的团队升级策略
   • Integration Type：选择“Events API V2”
5. 点击 Add Service 创建服务

​

2. 获取集成密钥

1. 在 Service Directory 中找到并点击刚创建的服务
2. 选择 Integrations 选项卡
3. 找到“Events API V2”集成
4. 复制 Integration Key（由 32 个字符组成的字母数字字符串）

​

3. 在 LangSmith 中配置使用 PagerDuty 的警报

1. 在 LangSmith 警报设置的通知部分，选择 PagerDuty
2. 点击密钥图标，将 Integration Key 保存为 Workspace secret，或选择现有的 Workspace secret。最佳实践是将 Integration Key 保存为 Workspace Secret，而不是直接添加。这样可以在同一工作区的多个警报之间重复使用该密钥。
3. 配置其他通知选项：
   • Severity：映射到 PagerDuty 事件优先级
4. 点击 Send Test Alert 发送测试警报
5. 验证 PagerDuty 是否触发了事件，并且事件包含相关的 LangSmith 警报信息

​

故障排查

• 验证 LangSmith 中输入的 Integration Key 是否正确
• 确保 PagerDuty 服务处于活动状态且未处于维护模式
• 检查 PagerDuty 账户是否启用了 Events API v2
• 如果 PagerDuty 中似乎缺少警报触发记录，请检查预期触发是否发生在同一警报规则上一次触发后的一个小时内，以及上一次警报创建的事件是否仍处于打开状态。
• 如果 LangSmith 实例位于防火墙之后，请检查网络连接

​

其他资源

• PagerDuty Events API v2 文档
• PagerDuty 集成指南

• 有效的 Dynatrace 环境（SaaS 或 Managed）。
• 具有 events.ingest 权限范围的 Dynatrace API 访问令牌。

​

1. 在 Dynatrace 中创建 API 令牌

1. 登录 Dynatrace 环境。
2. 进入 Access Tokens。
3. 点击 Generate new token。
4. 提供描述性名称（例如“LangSmith Alerts”）。
5. 在 Scopes 下搜索并启用 events.ingest（摄取事件）。
6. 点击 Generate token。
7. 复制生成的令牌并安全存储。该令牌只会显示一次。

​

2. 获取 Dynatrace 环境 URL

https://{your-environment-id}.live.dynatrace.com

​

3. 在 LangSmith 中配置使用 Dynatrace 的警报

1. 在 LangSmith 警报设置的 Notifications Settings 中，选择 Dynatrace。
2. 输入 Dynatrace 环境 URL。
3. 点击密钥图标，将 API 令牌保存为 workspace secret，或选择现有的 workspace secret。最佳实践是将 API 令牌保存为 workspace secret，而不是直接添加。这样可以在同一工作区的多个警报之间重复使用该令牌。
4. 配置其他通知选项：
   • Event Type：选择 Dynatrace 事件类型（例如 CUSTOM_ALERT、ERROR_EVENT）
5. 点击 Send Test Notification 发送测试警报。
6. 验证事件是否出现在 Dynatrace 环境中。

​

故障排查

• 验证 API 令牌具有 events.ingest 权限范围且未过期。
• 确保环境 URL 正确，并且包含环境 ID。
• 确认 Authorization 请求头使用 Api-Token 格式，而不是 Bearer。
• 检查 Dynatrace 环境是否处于活动状态且可以访问。
• 如果 LangSmith 实例位于防火墙之后，请检查网络连接。

​

其他资源

• Dynatrace Events API v2 文档
• Dynatrace 访问令牌

• 能够接收 HTTP POST 请求的端点
• 接收服务所需的适当身份验证凭据（如果需要）

​

1. 准备接收端点

• 接受 HTTP POST 请求
• 能够处理 JSON 负载
• 可以从外部服务访问
• 具有适当的身份验证机制（如果需要）

​

2. 配置 webhook 参数

• URL：接收端点的完整 URL
  • 示例：https://api.example.com/incident-webhook

• Headers：随 webhook 请求发送的 JSON 键值对
  • 常见请求头包括：
    • Authorization：用于身份验证令牌
    • Content-Type：通常设置为 application/json（默认值）
    • X-Source：用于标识来源为 LangSmith
  • 如果没有请求头，请使用 {}
• Request Body Template：自定义发送到端点的 JSON 负载
  • 默认情况下，LangSmith 会发送指定的负载，并将以下键值对追加到负载中：
    • project_name：触发警报的项目名称
    • alert_rule_id：用于标识 LangSmith 警报的 UUID。可将其用作 webhook 服务中的去重键。
    • alert_rule_name：警报规则名称。
    • alert_rule_type：警报类型（截至 2025 年 4 月 1 日，所有警报的类型均为 threshold）。
    • alert_rule_attribute：与警报规则关联的属性——error_count、feedback_score、latency 或 cost。
    • triggered_metric_value：触发阈值时的指标值。
    • triggered_threshold：触发警报的阈值。
    • timestamp：触发警报的时间戳。

​

3. 测试 webhook

​

故障排查

• 验证 webhook URL 是否正确且可访问
• 确保身份验证请求头格式正确
• 检查接收端点是否接受 POST 请求
• 查看端点日志，检查是否收到但拒绝了请求
• 验证自定义负载模板是否为有效的 JSON 格式

​

安全注意事项

• 为 webhook 端点使用 HTTPS
• 为 webhook 端点实现身份验证
• 考虑在请求头中添加共享密钥，以验证 webhook 来源
• 处理传入的 webhook 请求前先进行验证

​

示例方案

Configure Slack notifications via webhook

以下示例展示了如何使用 chat.postMessage API，将 LangSmith 警报通知发送到 Slack 频道。前置条件

• 访问 Slack 工作区的权限。
• 已设置警报的 LangSmith 项目。
• 创建 Slack 应用的权限。

步骤 1：创建 Slack 应用

1. 访问 Slack API 应用页面。
2. 点击 Create New App。
3. 选择 From scratch。
4. 提供 App Name（例如“LangSmith Alerts”）。
5. 选择要安装该应用的工作区。
6. 点击 Create App。

步骤 2：配置机器人权限

1. 在 Slack 应用配置的左侧边栏中，点击 OAuth & Permissions。
2. 在 Scopes 下找到 Bot Token Scopes，然后点击 Add an OAuth Scope。
3. 添加以下权限范围：
   • chat:write（以应用身份发送消息）。
   • chat:write.public（向应用未加入的频道发送消息）。
   • channels:read（查看基本频道信息）。

步骤 3：将应用安装到工作区

1. 滚动到 OAuth & Permissions 页面顶部。
2. 点击 Install to Workspace。
3. 查看权限，然后点击 Allow。
4. 复制显示的 Bot User OAuth Token（以 xoxb- 开头）。

步骤 4：将机器人添加到 Slack 频道将机器人添加到要接收警报的特定频道。你可以在消息输入框中提及机器人（例如 @botname），将其添加到 Slack 频道。你还需要频道 ID，才能在 LangSmith 中配置 webhook 警报。打开频道详细信息 > About，即可找到频道 ID。步骤 5：在 LangSmith 中配置 webhook 警报

1. 在 LangSmith 中进入你的项目。
2. 选择 Alerts → Create Alert。
3. 定义警报指标和条件。
4. 在通知部分选择 Webhook。
5. 使用以下设置配置 webhook：

Webhook URL

https://slack.com/api/chat.postMessage

Headers

将 xoxb-your-token-here 替换为机器人用户的 OAuth Token

{
  "Content-Type": "application/json",
  "Authorization": "Bearer xoxb-your-token-here"
}

Request Body Template

必须将第 4 步中获取的值填入 {channel_id}。

其余字段 alert_name、project_name 和 project_url 可以选择性地为警报添加更多上下文。你可以在浏览器地址栏中找到 project_url。复制 URL 中直到查询参数之前的部分。

{
  "channel": "{channel_id}",
  "text": "{alert_name} triggered for {project_name}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚨{alert_name} has been triggered"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Please check the following link for more information:"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<{project-url}|View in LangSmith>"
      }
    }
  ]
}

6. 点击 Save 激活 webhook 配置。

步骤 6：测试集成

1. 在 LangSmith 警报配置中，点击 Test Alert。
2. 检查指定的 Slack 频道，确认是否收到测试通知。
3. 验证消息是否包含预期的警报信息。

（可选）步骤 7：在请求正文中链接到警报预览创建警报后，你可以选择在 webhook 请求正文中链接到该警报的预览页面。配置方法如下：

1. 保存警报。
2. 在警报表格中找到已保存的警报并点击它。
3. 复制显示的 URL。
4. 点击“Edit Alert”。
5. 将现有项目 URL 替换为复制的警报预览 URL。

https://prod-XX.westus.logic.azure.com:443/workflows/.../triggers/manual/paths/invoke?...

{
  "Content-Type": "application/json"
}

{}

https://api.sendgrid.com/v3/mail/send

{
  "Content-Type": "application/json",
  "Authorization": "Bearer SG.your-api-key-here"
}

{
  "personalizations": [
    {
      "to": [
        {
          "email": "oncall@your-company.com"
        }
      ],
      "subject": "LangSmith alert triggered"
    }
  ],
  "from": {
    "email": "alerts@your-company.com",
    "name": "LangSmith Alerts"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "A LangSmith alert was triggered. Open your LangSmith workspace to view the alert details, including the project, metric value, threshold, and timestamp."
    }
  ]
}

​

其他资源

• Slack chat.postMessage API 文档
• Slack Block Kit Builder
• 使用 Workflows 为 Microsoft Teams 创建传入 webhook
• Power Automate 文档
• langsmith-teams-webhook 示例仓库
• SendGrid Mail Send API 文档