LangSmith 中的警报 - Docs by LangChain

自托管版本要求访问警报功能需要 Helm chart 版本 0.10.3 或更高版本。

概述

在 LLM 应用中实现有效的可观测性，需要主动检测故障、性能下降和回退。LangSmith 的警报功能有助于识别关键问题，例如：

来自模型提供商的 API 速率限制违规
应用程序延迟增加
影响反映最终用户体验的反馈分数的应用程序更改
LLM 使用导致的意外成本飙升

LangSmith 中的警报是项目范围的，需要为每个受监控的项目单独配置。

配置警报

步骤 1：导航至创建警报

在 UI 中，导航到您想要配置警报的 Tracing 项目。点击页面右上角的警报图标，以查看该项目的现有警报并设置新警报。

步骤 2：选择指标类型

LangSmith 提供基于阈值的警报，支持以下指标：

指标类型	描述	用例
运行次数	跟踪时间窗口内的总运行次数。	监控管道是否以预期的卷产生运行，并在意外下降时发出警报。
成本	跟踪时间窗口内运行的总成本。	监控 LLM 支出，在成本超过预期阈值时发出警报。需要配置成本跟踪。
错误	跟踪具有错误状态的运行。对总错误数或错误百分比（错误运行次数占所有运行次数的比例）发出警报。	监控应用程序中的故障，或在错误率超过可接受阈值时发出警报。
反馈分数	衡量平均反馈分数。	跟踪来自最终用户的反馈或在线评估结果，以在出现回退时发出警报。
延迟	衡量平均运行执行时间。	跟踪应用程序的延迟，以在出现峰值和性能瓶颈时发出警报。

此外，对于错误和延迟，您可以定义过滤器以缩小触发警报的运行范围。例如，您可以为所有标记为 support_agent 且遇到 RateLimitExceeded 错误的 llm 运行创建一个错误警报过滤器。

步骤 2：定义警报条件

警报条件由几个部分组成：

聚合方法：平均值、百分比或计数
比较运算符：>=、<= 或超过阈值
阈值数值：触发警报的数值
聚合窗口：用于计算指标的时间段（目前可选择 5 或 15 分钟）
反馈键（仅限反馈分数警报）：要监控的特定反馈指标

示例： 上面显示的配置将在过去 5 分钟内超过 5% 的运行导致错误时生成警报。您可以预览历史时间窗口内的警报行为，以了解在选定阈值（以红色指示）下，有多少数据点——以及哪些数据点——会触发警报。例如，为项目设置 60 秒的平均延迟阈值，可以让您可视化潜在的警报，如下图所示。

步骤 3：配置通知渠道

PagerDuty
Dynatrace
Webhook

使用 PagerDuty 的 Events API v2 将 PagerDuty 配置为通知渠道。此集成允许关键的 LLM 应用问题触发 PagerDuty 事件，从而通过您已建立的事件管理工作流实现快速响应。先决条件

一个具有管理员访问权限的活跃 PagerDuty 账户
在 PagerDuty 中具有适当的服务级权限

如果使用 LangSmith 的自定义部署，请确保没有防火墙设置阻止来自 LangSmith 服务的出站流量。

1. 在 PagerDuty 中创建服务

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

2. 获取集成密钥

创建服务后，检索集成密钥：

从 Service Directory 中，找到并点击您新创建的服务
选择 Integrations 选项卡
找到 “Events API V2” 集成
复制 Integration Key（一个 32 位的字母数字字符串）

3. 使用 PagerDuty 配置 LangSmith 警报

要在警报触发后一小时内再次收到相同的警报，您必须在 PagerDuty 中解决由警报创建的活跃事件。

在 LangSmith 中警报设置的通知部分，选择 PagerDuty
点击钥匙图标将集成密钥保存为工作区密钥，或选择现有的工作区密钥。作为最佳实践，我们建议将集成密钥保存为工作区密钥，而不是直接添加。这将允许您在工作区的警报中重复使用相同的密钥。
配置其他通知选项：
- 严重性：映射到 PagerDuty 事件优先级
点击 Send Test Alert 发送测试警报
验证 PagerDuty 是否触发了事件，并包含相关的 LangSmith 警报信息

故障排除

如果 PagerDuty 中未创建事件：

验证集成密钥在 LangSmith 中输入正确
确保 PagerDuty 服务处于活动状态且未处于维护模式
检查您的 PagerDuty 账户是否启用了 Events API v2
如果 PagerDuty 中似乎缺少警报触发器，请检查预期的触发器是否在来自同一警报规则的先前触发器的一小时内发生，以及先前警报创建的事件是否仍然开放。
如果您的 LangSmith 实例位于防火墙后，请检查网络连接

附加资源

使用 Dynatrace 的 Events API v2 将 Dynatrace 配置为通知渠道。此集成将 LangSmith 警报事件发送到您的 Dynatrace 环境，从而能够与更广泛的基础设施监控进行关联。先决条件

一个活跃的 Dynatrace 环境（SaaS 或 Managed）。
一个具有 events.ingest 作用域的 Dynatrace API 访问令牌。

如果您使用的是 LangSmith 的自定义部署，请确保没有防火墙设置阻止来自 LangSmith 服务的出站流量。

1. 在 Dynatrace 中创建 API 令牌

登录您的 Dynatrace 环境。
导航至 Access Tokens。
点击 Generate new token。
提供一个描述性名称（例如 “LangSmith Alerts”）。
在 Scopes 下，搜索并启用 events.ingest（Ingest events）。
点击 Generate token。
复制生成的令牌并安全存储。该令牌仅显示一次。

2. 获取您的 Dynatrace 环境 URL

您的 Dynatrace 环境 URL 遵循以下格式：

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

您可以在登录 Dynatrace 时在浏览器 URL 栏中找到您的环境 ID。

3. 使用 Dynatrace 配置 LangSmith 警报

在 LangSmith 中警报设置的 Notifications Settings 中，选择 Dynatrace。
输入您的 Dynatrace 环境 URL。
点击钥匙图标将 API 令牌保存为工作区密钥，或选择现有的工作区密钥。作为最佳实践，将 API 令牌保存为工作区密钥，而不是直接添加。这允许您在工作区的警报中重复使用相同的令牌。
配置其他通知选项：
- Event Type：选择 Dynatrace 事件类型（例如 CUSTOM_ALERT、ERROR_EVENT）
点击 Send Test Notification 发送测试警报。
验证事件是否出现在您的 Dynatrace 环境中。

故障排除

如果事件未出现在 Dynatrace 中：

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

附加资源

Webhook 通过在警报条件触发时发送 HTTP POST 请求，实现与自定义服务和第三方平台的集成。使用 Webhook 将警报数据转发到工单系统、聊天应用程序或自定义监控解决方案。先决条件

一个可以接收 HTTP POST 请求的端点
您接收服务的适当身份验证凭据（如果需要）

1. 准备您的接收端点

在 LangSmith 中配置 Webhook 之前，请确保您的接收端点：

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

如果使用 LangSmith 的自定义部署，请确保没有防火墙设置阻止来自 LangSmith 服务的出站流量。

2. 配置 Webhook 参数

在警报的通知部分，使用以下参数完成 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

点击 Send Test Alert 发送 Webhook 通知，以确保通知按预期工作。

故障排除

如果 Webhook 通知未被送达：

验证 Webhook URL 是否正确且可访问
确保任何身份验证标头格式正确
检查您的接收端点是否接受 POST 请求
检查端点日志中已接收但被拒绝的请求
验证您的自定义有效负载模板是否为有效的 JSON 格式

安全注意事项

对您的 Webhook 端点使用 HTTPS
为您的 Webhook 端点实施身份验证
考虑在标头中添加共享密钥以验证 Webhook 来源
在处理传入的 Webhook 请求之前对其进行验证

将警报发送到 Slack

通过 Webhook 配置 Slack 通知

以下是配置 LangSmith 警报以使用 chat.postMessage API 向 Slack 频道发送通知的示例。先决条件

访问 Slack 工作区
一个用于设置警报的 LangSmith 项目
创建 Slack 应用程序的权限

步骤 1：创建 Slack 应用

访问 Slack API Applications 页面
点击 Create New App
选择 From scratch
提供一个 App Name（例如 “LangSmith Alerts”）
选择您要安装应用的工作区
点击 Create App

步骤 2：配置机器人权限

在 Slack 应用配置的左侧边栏中，点击 OAuth & Permissions
向下滚动到 Scopes 下的 Bot Token Scopes，然后点击 Add an OAuth Scope
添加以下作用域：
- chat:write（以应用身份发送消息）
- chat:write.public（向应用未加入的频道发送消息）
- channels:read（查看基本频道信息）

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

向上滚动到 OAuth & Permissions 页面顶部
点击 Install to Workspace
查看权限并点击 Allow
复制出现的 Bot User OAuth Token（以 xoxb- 开头）

步骤 4：将机器人添加到 Slack 频道将机器人添加到您希望接收警报的特定频道。您可以通过在消息字段中提及机器人（例如 @botname）来将其添加到 Slack 频道。您还需要频道 ID 来在 LangSmith 中配置 Webhook 警报。您可以通过打开频道详情 > About 来找到频道 ID。步骤 5：在 LangSmith 中配置 Webhook 警报

在 LangSmith 中，导航到您的项目
选择 Alerts → Create Alert
定义您的警报指标和条件
在通知部分，选择 Webhook
使用以下设置配置 Webhook：

Webhook URL

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

Headers

将 xoxb-your-token-here 替换为您的机器人的 User OAuth Token

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

Request Body Template

需要填写从步骤 4 中找到的值中的 {channel_id}。

其余字段：alert_name、project_name 和 project_url 可选地为警报消息添加额外上下文。您可以在浏览器的 URL 栏中找到您的 project_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>"
      }
    }
  ]
}

点击 Save 以激活 Webhook 配置

步骤 6：测试集成

在 LangSmith 警报配置中，点击 Test Alert
检查您指定的 Slack 频道中的测试通知
验证消息是否包含预期的警报信息

（可选）步骤 7：在请求体中链接到警报预览创建警报后，您可以选择在 Webhook 的请求体中链接到其预览。

要配置此项：

保存您的警报
在警报表中找到您保存的警报并点击它
复制显示的 URL
点击 “Edit Alert”
将现有的项目 URL 替换为复制的警报预览 URL

附加资源

最佳实践

根据应用程序的关键性调整灵敏度
从更宽的阈值开始，并根据观察到的模式进行细化
确保警报路由到达适当的值班人员

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​概述

​配置警报

​步骤 1：导航至创建警报

​步骤 2：选择指标类型

​步骤 2：定义警报条件

​步骤 3：配置通知渠道

​1. 在 PagerDuty 中创建服务

​2. 获取集成密钥

​3. 使用 PagerDuty 配置 LangSmith 警报

​故障排除

​附加资源

​1. 在 Dynatrace 中创建 API 令牌

​2. 获取您的 Dynatrace 环境 URL

​3. 使用 Dynatrace 配置 LangSmith 警报

​故障排除

​附加资源

​1. 准备您的接收端点

​2. 配置 Webhook 参数

​3. 测试 Webhook

​故障排除

​安全注意事项

​将警报发送到 Slack

​附加资源

​最佳实践

概述

配置警报

步骤 1：导航至创建警报

步骤 2：选择指标类型

步骤 2：定义警报条件

步骤 3：配置通知渠道

1. 在 PagerDuty 中创建服务

2. 获取集成密钥

3. 使用 PagerDuty 配置 LangSmith 警报

故障排除

附加资源

1. 在 Dynatrace 中创建 API 令牌

2. 获取您的 Dynatrace 环境 URL

3. 使用 Dynatrace 配置 LangSmith 警报

故障排除

附加资源

1. 准备您的接收端点

2. 配置 Webhook 参数

3. 测试 Webhook

故障排除

安全注意事项

将警报发送到 Slack

附加资源

最佳实践