langsmith-trace

两个主要主题：**为应用添加追踪**，以及**查询追踪数据**以进行调试和分析。支持 Python 和 Javascript 实现。 环境变量

LANGSMITH_API_KEY=lsv2_pt_your_api_key_here          # REQUIRED
LANGSMITH_PROJECT=your-project-name                   # Optional: default project
LANGSMITH_WORKSPACE_ID=your-workspace-id              # Optional: for org-scoped keys

必须进行身份验证：设置 LANGSMITH_API_KEY 环境变量，或在 CLI 命令中传入 --api-key 标志（推荐）：

langsmith trace list --project my-project --api-key $LANGSMITH_API_KEY

重要： 在查询或与 LangSmith 交互之前，请务必检查环境变量或 .env 文件中的 LANGSMITH_PROJECT。它会告知你相关追踪数据和数据所在的项目。如果无法确定 LangSmith 项目，请自行判断合适的项目。

CLI 工具

curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

<cli_feedback> 如果 CLI 实际运行失败、需要未记录的变通方法、输出令人困惑或缺少某项功能，请针对任务中的每个不同问题提交一条简短的产品反馈。不要报告被追踪应用自身的常规成功或失败。

CLI 要求： langsmith feedback 需要 LangSmith CLI v0.2.58 或更高版本。使用 langsmith --version 检查已安装的版本。

查看 langsmith feedback --help，确认是否提供 feedback <note> 和 --category；如果没有，请跳过反馈，不要使用原始 HTTP 请求或未发布的构建版本。使用现有的已验证配置、端点和工作区。反馈会发送到 LangSmith Cloud，包括通过 BYOC 中继发送的情况；如果是独立的自托管环境，请跳过。遵守用户和组织的限制；如果不确定是否获准发送，请先询问。

用你自己的话概述 CLI 的预期行为与实际观察到的行为，以及任何变通方法。切勿发送密钥、客户数据、追踪负载、提示词、完整堆栈跟踪、复制的命令输出、原始参数、环境变量值、本地路径或资源标识符。CLI 会附加版本、操作系统和架构信息，但不会对你的反馈内容进行脱敏；如果无法安全脱敏，请跳过反馈。

选择 bug、feature-request、usability、documentation 或 other。这是 CLI 产品反馈，不是运行评估反馈。以下仅为格式示例——只有实际遇到问题时才提交：

langsmith feedback --category usability --format json "The trace list output made it hard to distinguish root runs from child runs."

不要重试失败或被限流的反馈提交，不要切换凭据或端点来绕过失败，也不要因反馈而阻碍原任务。 </cli_feedback>

<trace_langchain_oss> 对于 LangChain/LangGraph 应用，追踪会自动进行。只需设置环境变量：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
export OPENAI_API_KEY=<your-openai-api-key>  # or your LLM provider's key

可选变量：

• LANGSMITH_PROJECT - 指定项目名称（默认为 "default"）
• LANGCHAIN_CALLBACKS_BACKGROUND=false - 用于无服务器环境，确保函数退出前追踪完成（Python） </trace_langchain_oss>

<trace_other_frameworks> 对于非 LangChain 应用，如果框架原生支持 OpenTelemetry，请使用 LangSmith 的 OpenTelemetry 集成。

如果应用没有使用框架，或使用的框架不支持自动 OTel 追踪，请使用可追踪装饰器/包装器，并包装 LLM 客户端。

使用 @traceable 装饰器和 wrap_openai() 实现自动追踪。 ```python from langsmith import traceable from langsmith.wrappers import wrap_openai from openai import OpenAI

client = wrap_openai(OpenAI())

@traceable def my_llm_pipeline(question: str) -> str: resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": question}], ) return resp.choices[0].message.content

Nested tracing example

@traceable def rag_pipeline(question: str) -> str: docs = retrieve_docs(question) return generate_answer(question, docs)

@traceable(name="retrieve_docs") def retrieve_docs(query: str) -> list[str]: return docs

@traceable(name="generate_answer") def generate_answer(question: str, docs: list[str]) -> str: return client.chat.completions.create(...)

</python>

<typescript>
使用 traceable() 包装器和 wrapOpenAI() 实现自动追踪。
```typescript
import { traceable } from "langsmith/traceable";
import { wrapOpenAI } from "langsmith/wrappers";
import OpenAI from "openai";

const client = wrapOpenAI(new OpenAI());

const myLlmPipeline = traceable(async (question: string): Promise<string> => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: question }],
  });
  return resp.choices[0].message.content || "";
}, { name: "my_llm_pipeline" });

// Nested tracing example
const retrieveDocs = traceable(async (query: string): Promise<string[]> => {
  return docs;
}, { name: "retrieve_docs" });

const generateAnswer = traceable(async (question: string, docs: string[]): Promise<string> => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: `${question}\nContext: ${docs.join("\n")}` }],
  });
  return resp.choices[0].message.content || "";
}, { name: "generate_answer" });

const ragPipeline = traceable(async (question: string): Promise<string> => {
  const docs = await retrieveDocs(question);
  return await generateAnswer(question, docs);
}, { name: "rag_pipeline" });

最佳实践：

• 对所有希望在 LangSmith 中显示的嵌套函数应用 traceable
• 包装后的客户端会自动追踪所有调用 — wrap_openai()/wrapOpenAI() 会记录每次 LLM 调用
• 为追踪命名，以便更轻松地筛选
• 添加元数据，以便搜索 </trace_other_frameworks>

<traces_vs_runs> 使用 langsmith CLI 查询追踪数据。

理解两者的区别至关重要：

• 追踪（Trace） = 完整的执行树（根运行 + 所有子运行）。一次追踪表示一次完整的 Agent 调用，包含所有 LLM 调用、工具调用和嵌套操作。
• 运行（Run） = 树中的单个节点（一次 LLM 调用、一次工具调用等）。

通常应先查询追踪——追踪提供完整上下文并保留层级结构，这对轨迹分析和数据集生成至关重要。 </traces_vs_runs> <command_structure> 两个命令组，行为一致：

langsmith
├── trace (operations on trace trees - USE THIS FIRST)
│   ├── list    - List traces (filters apply to root run)
│   ├── get     - Get single trace with full hierarchy
│   └── export  - Export traces to JSONL files (one file per trace)
│
├── run (operations on individual runs - for specific analysis)
│   ├── list    - List runs (flat, filters apply to any run)
│   ├── get     - Get single run
│   └── export  - Export runs to single JSONL file (flat)
│
├── dataset (dataset operations)
│   ├── list    - List datasets
│   ├── get     - Get dataset details
│   ├── create  - Create empty dataset
│   ├── delete  - Delete dataset
│   ├── export  - Export dataset to file
│   └── upload  - Upload local JSON as dataset
│
├── example (example operations)
│   ├── list    - List examples in a dataset
│   ├── create  - Add example to a dataset
│   └── delete  - Delete an example
│
├── evaluator (evaluator operations)
│   ├── list    - List evaluators
│   ├── upload  - Upload evaluator
│   └── delete  - Delete evaluator
│
├── experiment (experiment operations)
│   ├── list    - List experiments
│   └── get     - Get experiment results
│
├── thread (thread operations)
│   ├── list    - List conversation threads
│   └── get     - Get thread details
│
└── project (project operations)
    └── list    - List tracing projects

主要区别：

	traces *	runs *
筛选条件适用范围	仅根运行	任何匹配的运行
--run-type	不可用	可用
返回内容	完整层级结构	扁平列表
导出结果	目录（每条轨迹一个文件）	单个文件
</command_structure>

<querying_traces> 使用 langsmith CLI 查询轨迹。命令与编程语言无关。

# List recent traces (most common operation)
langsmith trace list --limit 10 --project my-project --api-key $LANGSMITH_API_KEY

# List traces with metadata (timing, tokens, costs)
langsmith trace list --limit 10 --include-metadata --api-key $LANGSMITH_API_KEY

# Filter traces by time
langsmith trace list --last-n-minutes 60 --api-key $LANGSMITH_API_KEY
langsmith trace list --since 2025-01-20T10:00:00Z --api-key $LANGSMITH_API_KEY

# Get specific trace with full hierarchy
langsmith trace get <trace-id> --api-key $LANGSMITH_API_KEY

# List traces and show hierarchy inline
langsmith trace list --limit 5 --show-hierarchy --api-key $LANGSMITH_API_KEY

# Export traces to JSONL (one file per trace, includes all runs)
langsmith trace export ./traces --limit 20 --full --api-key $LANGSMITH_API_KEY

# Filter traces by performance
langsmith trace list --min-latency 5.0 --limit 10 --api-key $LANGSMITH_API_KEY    # Slow traces (>= 5s)
langsmith trace list --error --last-n-minutes 60 --api-key $LANGSMITH_API_KEY     # Failed traces

# List specific run types (flat list)
langsmith run list --run-type llm --limit 20 --api-key $LANGSMITH_API_KEY

</querying_traces>

所有命令都支持以下筛选条件（条件之间均为 AND 关系）：

基本筛选条件：

• --trace-ids abc,def - 筛选指定的轨迹
• --limit N - 最大结果数
• --project NAME - 项目名称
• --last-n-minutes N - 时间筛选
• --since TIMESTAMP - 时间筛选（ISO 格式）
• --error / --no-error - 错误状态
• --name PATTERN - 名称包含（不区分大小写）

性能筛选条件：

• --min-latency SECONDS - 最小延迟（例如，5 表示 >= 5s）
• --max-latency SECONDS - 最大延迟
• --min-tokens N - 最小总令牌数
• --tags tag1,tag2 - 包含这些标签中的任意一个

高级筛选条件：

• --filter QUERY - 原始 LangSmith 筛选查询，用于复杂情况（反馈、元数据等）

# Filter traces by feedback score using raw LangSmith query
langsmith trace list --filter 'and(eq(feedback_key, "correctness"), gte(feedback_score, 0.8))' --api-key $LANGSMITH_API_KEY

<export_format> 导出会创建 .jsonl 文件（每行一条运行记录），包含以下字段：

{"run_id": "...", "trace_id": "...", "name": "...", "run_type": "...", "parent_run_id": "...", "inputs": {...}, "outputs": {...}}

使用 --include-io 或 --full 可包含输入/输出（生成数据集时必需）。 </export_format>

- **从轨迹开始**——轨迹提供生成轨迹路径和数据集所需的完整上下文 - 对于用于数据集的批量数据，请使用 `trace export --full` - 始终指定 `--project`，以避免混合不同项目的数据 - 临时导出请使用 `/tmp` - 添加 `--include-metadata`，用于性能/成本分析 - 合并文件：`cat ./traces/*.jsonl > all.jsonl`