以编程方式使用文档

本页提供诊断步骤，帮助您对自托管 LangSmith Deployment 进行故障排除。在联系支持部门之前，请系统地遵循这些步骤来识别和解决常见的部署问题。

前提条件

在开始诊断步骤之前，请确保您具备：

  • - kubectl 访问 Kubernetes 集群的权限。
  • - 查看 pods、deployments、services 等的适当权限。
  • - 熟悉您的 Helm chart 配置.

第 1 步。了解您的部署

验证已部署的内容并了解系统的基线状态。这有助于您识别正常运行时的状态，并在出现问题时发现偏差。

运行以下命令查看所有已部署的 Kubernetes 资源。

列出所有 deployments：

kubectl get deployments

列出所有 pods：

kubectl get pods

列出所有服务：

kubectl get services

列出所有 lgps 资源（仅在创建后出现 Agent Server):

kubectl get lgps

已部署的关键组件

您的部署包含以下核心组件：

  • - **langsmith-frontend**：LangSmith 前端 UI，您可在此创建 Agent Server 部署。此应用向以下服务调用 API langsmith-host-backend。这是 控制平面.
  • - **langsmith-host-backend**：LangSmith 部署 控制平面 ，负责接收来自 langsmith-frontend 的请求，并将部署请求持久化到控制平面 Postgres 数据库。
  • - **langsmith-listener**：LangSmith 部署 数据平面的一部分。通过 HTTP API 轮询 langsmith-host-backend 以创建、更新或删除部署。将任务加入队列供工作进程处理。
  • - **langsmith-redis**： Redis 实例，作为 langsmith-listener的任务队列。监听器在此将任务加入队列，工作进程从该队列中获取任务。
  • - **langsmith-operator**： lgps Kubernetes operator，负责调谐 lgps 资源的底层 Kubernetes 资源。作为数据平面基础设施的一部分。

步骤 2. 启用调试日志

排查问题时，第一步通常是启用调试级别日志，以收集有关系统运行情况的更详细信息。

对于控制平面或数据平面部署

如果您遇到控制平面部署问题（例如， langsmith-host-backend）或数据平面部署问题（例如， langsmith-listener），请使用以下方式重新安装 Helm chart LOG_LEVEL=DEBUG 环境变量。将以下内容添加到您的 values.yaml file:

extraEnv:
  - name: LOG_LEVEL
    value: DEBUG

对于 Agent Server 部署

如果问题出在单个 Agent Server 部署上：

  1. 导航到 **部署** 标签页 LangSmith UI.
  2. 在部署视图中，选择 **+ 新建修订版本**.
  3. 添加一个新的环境变量 LOG_LEVEL 并将其设置为 DEBUG.

对于广泛性问题

如果您不确定问题来源，请在所有地方启用 DEBUG 日志记录（控制平面、数据平面和所有 Agent Server 部署）。

查看应用程序日志

追踪每个 pod 的日志以了解基线行为：

kubectl logs -f <pod_name>

然后查找以下日志行：

  • - **langsmith-listener**: Reconciling projects... （每 10 秒出现一次）
  • - **langsmith-operator**: Starting reconciliation （定期出现）

在健康运行的部署中，您不应该看到任何错误。所有日志都应显示正常和例行。

解读调试日志

查找以下问题指标：

  • - 异常或堆栈跟踪。
  • - 错误消息（单词 "ERROR").
  • - 与正常操作不同的异常模式。

根据您发现的错误：

  • 配置问题：如果您怀疑是配置问题，请向运行 helm install.
  • 用户代码错误：如果您怀疑是用户代码中的错误（例如，LangGraph OSS 图实现），请向创建了该 langgraph.json file.

步骤 3. 描述部署和 Pod

描述 Kubernetes 资源可以揭示应用程序日志中可能未显示的错误事件和状态。这些错误通常由配置或基础设施问题引起，而不是应用程序代码错误。描述资源还会显示其配置（如环境变量），这有助于调试。

运行以下命令来描述您的资源。

描述 Kubernetes 部署：

kubectl describe deployment <deployment_name>

描述 Kubernetes Pod：

kubectl describe pod <pod_name>

描述一个 lgps 资源（仅在创建 Agent Server 后适用）：

kubectl describe lgps <lgps_name>

解释结果

查看输出的 Events: 部分，验证一切正常。常见问题包括：

  • - 存活探针或就绪探针失败
  • - 镜像拉取错误
  • - 资源约束（CPU、内存）
  • - 卷挂载问题
  • - 配置错误

确保没有错误事件，所有事件都表明运行正常。

更多资源

如需更多故障排除信息，请参阅：

  • - 故障排除：包含常见问题解决方案的通用故障排除指南。
  • - 自托管概述：系统架构和组件交互的详细信息。

支持

如果您已按照这些诊断步骤操作但仍需帮助，请在联系支持团队之前收集以下信息：

  • - 诊断步骤的 输出结果.
  • - 您的 Helm chart 配置。
  • - 相关的错误信息和日志。
  • - 问题发生时您尝试执行的操作描述。

准备好这些信息将有助于 支持 团队更快地诊断和解决您的问题。