> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangSmith 中的警报

<Note>
  **自托管版本要求**

  访问警报功能需要 Helm chart 版本 **0.10.3** 或更高版本。
</Note>

## 概述

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

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

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

## 配置警报

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

在 [UI](https://smith.langchain.com) 中，导航到您想要配置警报的 Tracing 项目。点击页面右上角的 **警报** 图标，以查看该项目的现有警报并设置新警报。

### 步骤 2：选择指标类型

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

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

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

<div style={{ textAlign: 'center' }}>
  <img src="https://mintcdn.com/other-405835d4/6Toz5fHjgEZXpscE/langsmith/images/alerts-filter.png?fit=max&auto=format&n=6Toz5fHjgEZXpscE&q=85&s=c33b9dd18b2e24183aa39de3f71bd9e2" alt="警报指标" width="407" height="273" data-path="langsmith/images/alerts-filter.png" />
</div>

### 步骤 2：定义警报条件

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

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

<br />

<div style={{ textAlign: 'center' }}>
  <img src="https://mintcdn.com/other-405835d4/2a1kkFnfjfW0Zb-b/langsmith/images/define-conditions.png?fit=max&auto=format&n=2a1kkFnfjfW0Zb-b&q=85&s=49afacf4d47832c7e97d642dbce6b4f2" alt="警报条件配置" width="597" height="112" data-path="langsmith/images/define-conditions.png" />
</div>

**示例：** 上面显示的配置将在过去 5 分钟内超过 5% 的运行导致错误时生成警报。

您可以预览历史时间窗口内的警报行为，以了解在选定阈值（以红色指示）下，有多少数据点——以及哪些数据点——会触发警报。例如，为项目设置 60 秒的平均延迟阈值，可以让您可视化潜在的警报，如下图所示。

<div style={{ textAlign: 'center' }}>
  <img src="https://mintcdn.com/other-405835d4/6Toz5fHjgEZXpscE/langsmith/images/alert-preview.png?fit=max&auto=format&n=6Toz5fHjgEZXpscE&q=85&s=11a689daf4eca6c5fa06e2c72cabb461" alt="警报指标" width="863" height="545" data-path="langsmith/images/alert-preview.png" />
</div>

### 步骤 3：配置通知渠道

<Tabs>
  <Tab title="PagerDuty">
    使用 PagerDuty 的 [Events API v2](https://developer.pagerduty.com/docs/events-api-v2-overview) 将 PagerDuty 配置为通知渠道。此集成允许关键的 LLM 应用问题触发 PagerDuty 事件，从而通过您已建立的事件管理工作流实现快速响应。

    **先决条件**

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

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

    #### 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 位的字母数字字符串）

           <img src="https://mintcdn.com/other-405835d4/4uxGFmQj9AQhEaXK/langsmith/images/pager-duty.png?fit=max&auto=format&n=4uxGFmQj9AQhEaXK&q=85&s=f62e3e4d275a700cc3bab0d30037bd5b" alt="PagerDuty 集成密钥位置" width="1396" height="729" data-path="langsmith/images/pager-duty.png" />

    #### 3. 使用 PagerDuty 配置 LangSmith 警报

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

    <img src="https://mintcdn.com/other-405835d4/4uxGFmQj9AQhEaXK/langsmith/images/pagerduty-setup.png?fit=max&auto=format&n=4uxGFmQj9AQhEaXK&q=85&s=e918bc73faa0dc90902d4a93947a5131" alt="PagerDuty 设置" width="590" height="413" data-path="langsmith/images/pagerduty-setup.png" />

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

    #### 故障排除

    如果 PagerDuty 中未创建事件：

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

    #### 附加资源

    * [PagerDuty Events API v2 文档](https://developer.pagerduty.com/docs/events-api-v2/overview/)
    * [PagerDuty 集成指南](https://support.pagerduty.com/docs/services-and-integrations)
  </Tab>

  <Tab title="Dynatrace">
    使用 Dynatrace 的 [Events API v2](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/events-v2/post-event) 将 Dynatrace 配置为通知渠道。此集成将 LangSmith 警报事件发送到您的 Dynatrace 环境，从而能够与更广泛的基础设施监控进行关联。

    **先决条件**

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

    如果您使用的是 LangSmith 的自定义[部署](/langsmith/self-hosted)，请确保没有防火墙设置阻止来自 LangSmith 服务的出站流量。

    #### 1. 在 Dynatrace 中创建 API 令牌

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

    #### 2. 获取您的 Dynatrace 环境 URL

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

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

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

    #### 3. 使用 Dynatrace 配置 LangSmith 警报

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

    #### 故障排除

    如果事件未出现在 Dynatrace 中：

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

    #### 附加资源

    * [Dynatrace Events API v2 文档](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/events-v2/post-event)
    * [Dynatrace 访问令牌](https://docs.dynatrace.com/docs/manage/access-control/access-tokens)
  </Tab>

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

    **先决条件**

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

    #### 1. 准备您的接收端点

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

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

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

    #### 2. 配置 Webhook 参数

    <img src="https://mintcdn.com/other-405835d4/HWk8WH3Ivd1grcHm/langsmith/images/webhook-setup.png?fit=max&auto=format&n=HWk8WH3Ivd1grcHm&q=85&s=a72d714d0129acb1f1ef1de4be9b75ae" alt="Webhook 设置" width="754" height="523" data-path="langsmith/images/webhook-setup.png" />

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

    <Accordion title="通过 Webhook 配置 Slack 通知">
      以下是配置 LangSmith 警报以使用 [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) API 向 Slack 频道发送通知的示例。

      **先决条件**

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

      **步骤 1：创建 Slack 应用**

      1. 访问 [Slack API Applications 页面](https://api.slack.com/apps)
      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**

      ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      https://slack.com/api/chat.postMessage
      ```

      **Headers**
      <Note>将 `xoxb-your-token-here` 替换为您的机器人的 User OAuth Token</Note>

      ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      {
        "Content-Type": "application/json",
        "Authorization": "Bearer xoxb-your-token-here"
      }
      ```

      **Request Body Template**
      <Note>需要填写从步骤 4 中找到的值中的 `{channel_id}`。 <br /><br />其余字段：`alert_name`、`project_name` 和 `project_url` 可选地为警报消息添加额外上下文。您可以在浏览器的 URL 栏中找到您的 `project_url`。复制到但不包括任何查询参数的部分。</Note>

      ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      {
        "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 的请求体中链接到其预览。

      <img src="https://mintcdn.com/other-405835d4/6Toz5fHjgEZXpscE/langsmith/images/alert-preview-pane.png?fit=max&auto=format&n=6Toz5fHjgEZXpscE&q=85&s=9ce50186d2d3fd3ebfea68a7a6df11cb" alt="警报预览窗格" width="832" height="773" data-path="langsmith/images/alert-preview-pane.png" />

      要配置此项：

      1. 保存您的警报
      2. 在警报表中找到您保存的警报并点击它
      3. 复制显示的 URL
      4. 点击 "Edit Alert"
      5. 将现有的项目 URL 替换为复制的警报预览 URL
    </Accordion>

    #### 附加资源

    * [Slack chat.postMessage API 文档](https://api.slack.com/methods/chat.postMessage)
    * [Slack Block Kit Builder](https://app.slack.com/block-kit-builder/)
  </Tab>
</Tabs>

## 最佳实践

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

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/alerts.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>