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

<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/LangGraph 以外的任何框架，编写追踪代码前，请先阅读 references/ 中对应的参考文件。每份参考文件都涵盖安装、环境变量、设置代码片段，以及该框架特有的注意事项。不同框架的设置方式很少完全相同——选错模式（例如，框架原生支持 OTel，却使用 @traceable）会导致跨度重复或缺失。

选择顺序：

1. 框架有下方列出的专属参考文件 → 使用该文件
2. 框架原生支持 OpenTelemetry，但没有专属参考文件 → references/otel.md
3. 没有框架或框架不受支持 → references/traceable.md
4. 完全无法运行 LangSmith SDK → references/api.md（最后手段）

路由表：

如果要追踪……	阅读
OpenAI / Azure OpenAI / Anthropic / 任意普通 LLM 客户端	references/traceable.md
AutoGen	references/autogen.md
CrewAI	references/crewai.md
Google ADK	references/google-adk.md
Google Gemini（直接使用 google-genai SDK）	references/google-gemini.md
Instructor（结构化输出）	references/instructor.md
LiveKit Agents（语音 AI）	references/livekit.md
Mastra（TypeScript）	references/mastra.md
Microsoft Agent Framework	references/microsoft-agent-framework.md
Mistral	references/mistral.md
n8n（可自托管）	references/n8n.md
OpenAI Agents SDK	references/openai-agents-sdk.md
OpenCode	references/opencode.md
OpenAI Codex CLI	references/codex.md
Pipecat（语音 AI）	references/pipecat.md
PydanticAI	references/pydantic-ai.md
Semantic Kernel	references/semantic-kernel.md
Strands Agents	references/strands-agents.md
Temporal 工作流（Go/Python/TS）	references/temporal.md
Vercel AI SDK	references/vercel-ai-sdk.md
任何其他原生支持 OTel 的框架	references/otel.md
多后端 OTel 扇出	references/otel.md（Collector 部分）
原始 REST（没有可用的 SDK）	references/api.md

如果所需框架未列在此处，请查看 references/——新的集成会添加到那里，而不是写在此处。 </trace_other_frameworks>

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

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

• Trace（追踪） = 完整的执行树（根 run + 所有子 run）。一条追踪代表一次完整的 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

主要区别：

</command_structure>

	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 - 最少总 token 数
• --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>

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