可观测性

原文：Observability

一句话

可观测性功能通过 LangSmith 追踪（tracing）和调试工具，帮助开发者可视化 LangGraph 应用从输入到输出的执行步骤。

什么时候翻这页

需要调试本地运行的应用程序时
想评估应用程序性能时
需要监控应用程序运行状态时
希望选择性追踪特定调用或应用部分时
需要添加自定义元数据和标签到追踪中时
需要防止敏感数据被记录到追踪中时

核心概念

追踪（Tracing）：应用程序从输入到输出所经历的一系列步骤，每个步骤表示为一个运行（run）
LangSmith：LangChain 的平台，用于可视化、调试和监控 LangGraph 应用的执行步骤
项目（Project）：在 LangSmith 中组织追踪的逻辑容器
元数据（Metadata）：附加到追踪的自定义数据，用于组织和过滤追踪
标签（Tags）：用于分类和组织追踪的文本标记
匿名化器（Anonymizer）：用于从追踪中移除或替换敏感数据的工具

怎么做

启用追踪

设置环境变量启用追踪：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

选择性追踪

使用 tracing_context 上下文管理器选择性追踪特定调用：

import langsmith as ls

# 这将被追踪
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to alice@example.com"}]})

# 这将不会被追踪
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

记录到项目

静态设置

通过环境变量设置项目名称：

export LANGSMITH_PROJECT=my-agent-project

动态设置

在代码中动态设置项目名称：

import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "Send a welcome email"}]
    })

添加元数据到追踪

通过配置添加标签和元数据：

response = agent.invoke(
    {"messages": [{"role": "user", "content": "Send a welcome email"}]},
    config={
        "tags": ["production", "email-assistant", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)

使用匿名化器防止敏感数据被记录

创建匿名化器并应用到追踪：

from langchain_core.tracers.langchain import LangChainTracer
from langgraph.graph import StateGraph, MessagesState
from langsmith import Client
from langsmith.anonymizer import create_anonymizer

anonymizer = create_anonymizer([
    # 匹配社会保障号码格式
    { "pattern": r"\b\d{3}-?\d{2}-?\d{4}\b", "replace": "<ssn>" }
])

tracer_client = Client(anonymizer=anonymizer)
tracer = LangChainTracer(client=tracer_client)
# 定义图
graph = (
    StateGraph(MessagesState)
    ...
    .compile()
    .with_config({'callbacks': [tracer]})
)

命令 / API 速查

export LANGSMITH_TRACING=true - 启用追踪
export LANGSMITH_API_KEY=<your-api-key> - 设置 API 密钥
export LANGSMITH_PROJECT=<project-name> - 设置项目名称
ls.tracing_context() - 创建追踪上下文
create_anonymizer() - 创建匿名化器
Client(anonymizer=anonymizer) - 创建带匿名化器的客户端

与 Hello-Agents / Claude Code 的联系

在 Hello-Agents 中，我们了解了 LangGraph 的基本概念和构建方法，但没有深入探讨如何监控和调试这些工作流。可观测性功能填补了这一空白，它允许开发者：

验证 Hello-Agents 中构建的复杂工作流是否按预期执行
识别性能瓶颈和错误点
为不同环境（开发、测试、生产）设置不同的追踪配置

初学者易错点

忘记设置 LANGSMITH_API_KEY 环境变量，导致追踪无法工作
将敏感数据直接记录到追踪中，违反隐私和安全要求
混淆项目名称和环境变量，导致追踪数据分散在不同项目中
过度使用标签和元数据，导致追踪数据难以管理
在生产环境中启用详细追踪，可能影响性能和增加成本

语义检索