---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - langchain
  - langsmith
  - observability
  - tracing
topic: LangSmith 观测心智模型与追踪数据结构
sources:
  - https://docs.langchain.com/langsmith
  - https://docs.langchain.com/langsmith/components
  - https://docs.langchain.com/langsmith/feedback-data-format
  - https://docs.langchain.com/langsmith/manage-trace
  - https://docs.langchain.com/langsmith/observability
  - https://docs.langchain.com/langsmith/observability-concepts
  - https://docs.langchain.com/langsmith/observability-llm-tutorial
  - https://docs.langchain.com/langsmith/observability-quickstart
  - https://docs.langchain.com/langsmith/view-traces
last_verified: 2026-08-11
---

# LangSmith 观测心智模型与追踪数据结构

> [!summary]
> LangSmith 的核心不是“保存日志”，而是把一次 Agent 交互表达为可查询、可评估、可回放的运行树。生产设计应先稳定 trace、run、thread、project 的身份和边界，再谈图表、告警和评估。

## 学习导航

- [[02-SDK追踪上下文与分布式链路]]：如何正确创建、嵌套、传播和提交 span。
- [[03-LLM成本元数据多模态与检索]]：LLM、Retriever、消息、用量和附件的数据契约。
- [[04-查询过滤采样脱敏导出与用量]]：观测数据治理与查询面。
- [[05-监控仪表盘告警自动化与在线评估]]：从 trace 走向生产反馈闭环。
- [[06-集成矩阵-模型框架与编排]]：Provider、框架和编排系统的接入选择。
- [[07-编码代理语音与专用追踪]]：编码代理与语音 Agent 的特殊结构。
- [[08-OpenTelemetry采集器SDK与参考边界]]：OTel、Collector 与生成式 SDK 参考。
- [[09-Prompt工程版本治理与模型配置]]：Prompt 生命周期和模型配置。
- [[10-Context-Hub-Chat-MCP与Skills]]：上下文资产与诊断工具。
- [[11-LLM-Gateway架构接入与治理]]：模型流量统一入口。
- [[12-版本漂移重定向与生产检查清单]]：文档漂移和上线检查。

## 一、四个核心对象

| 对象 | 含义 | 生产边界 |
|---|---|---|
| Run / span | 一个有起止时间、输入输出、类型和状态的工作单元 | LLM、tool、retriever、chain 或自定义步骤 |
| Trace | 一棵以 root run 为根的 run 树 | 一次用户请求或一次完整会话动作；最多 25,000 个 runs |
| Thread | 多个 trace 按 <code>thread_id</code> 组成的时间序列 | 同一业务会话、工单或持续对话 |
| Project | trace 的逻辑容器，也称 tracing project/session | 应用 × 环境 × 数据边界，不应拿 tag 替代 |

Trace 的结构关系是：

    project
      └─ thread_id（可选）
           ├─ trace A：root run
           │    ├─ child LLM run
           │    └─ child tool run
           └─ trace B：root run

关键结论：

- run 在文档和 SDK 中也叫 span；不要把一次 trace 误称为一个 span。
- root run 的 ID 同时可成为 <code>trace_id</code>。子 run 通过 <code>parent_run_id</code> 与 <code>dotted_order</code> 定位层级和顺序。
- thread 不是另一棵 run 树，而是对多条 trace 的业务分组。没有稳定 thread ID，线程级成本、反馈和多轮评估都会失真。
- trajectory 是为多轮评估生成的扁平消息轨迹：LangSmith 会展开并去重重复消息；它不是原始 run 树的无损替代品。

## 二、Run 的最小生产数据契约

每个 run 至少要能回答：

1. 它是什么：稳定的 <code>name</code> 和正确的 <code>run_type</code>。
2. 它何时发生：<code>start_time</code>、<code>end_time</code>，流式 LLM 还应有首 token 时间。
3. 它处理了什么：结构化 <code>inputs</code> 与 <code>outputs</code>。
4. 它属于哪里：<code>trace_id</code>、父 run、project，必要时 <code>thread_id</code>。
5. 它是否成功：状态、错误与异常上下文。
6. 如何切片：tags、metadata、模型和集成元数据。

常用 run type：

- <code>chain</code>：业务编排、Agent、非模型函数。
- <code>llm</code>：真正的模型推理请求；决定消息渲染、token 和成本解析。
- <code>tool</code>：工具执行。
- <code>retriever</code>：检索步骤，输出应保留文档结构。
- <code>prompt</code>、<code>parser</code>：LangChain 等框架可产生的专用步骤。

不要为了“图好看”把所有节点标成 LLM。run type 是后续统计、Messages View、成本和评估的语义输入。

## 三、身份、顺序与幂等

- 新 run ID 推荐 UUIDv7。它带时间顺序，能降低并发子节点排序歧义。
- 同一事件重试时应复用 run ID，避免重复写；但“重复创建”和“重复更新”仍可能返回 409，调用方必须区分幂等重放与真实冲突。
- 批量/OTel 接入必须正确计算 <code>trace_id</code> 与 <code>dotted_order</code>。仅有 parent ID 不足以覆盖所有异步到达场景。
- 不要依赖 UI 展示顺序恢复业务因果；业务因果应在 run 层级、显式事件 ID 和 metadata 中可验证。

## 四、UI 的三种读法

### Details

用于看输入输出、metadata、tags、错误和父子层级。它最接近原始 run 数据。

### Waterfall

用于看并行/串行关系、跨度、瓶颈与首 token 延迟。长 trace 的 turn 标题可固定，但 turn 只是展示辅助，不应反推真实业务状态机。

### Messages

用于从 root trace 中重建主对话，合并重复的模型输入输出、工具调用和结果。它是一个适配层：

- 集成必须输出 LangSmith 能识别的消息结构。
- 中间 guardrail、子 Agent 对话可能被排除，以保持“主对话”可读。
- Messages 为空不代表 trace 没数据，可能只是格式适配失败。
- Details 是排查权威视图，Messages 是便于阅读的派生视图。

## 五、反馈不是日志字段

Feedback 是独立资源，可附着于 run 或 thread，用于人工标注、在线评估和纠错。常见字段包括：

- key：指标名称，必须长期稳定。
- score 或 value：数值或分类结果。
- comment / correction：解释与修正内容。
- source：人工、模型评估器或自动化来源。

生产约束：

- 不要把同一语义拆成频繁变化的 feedback key，否则仪表盘无法形成连续时间序列。
- thread feedback 与 run feedback 的粒度不同；多轮结果不要强行写到任意末次 run。
- 评估器重命名不改变既有 feedback key；重命名前先评估指标连续性。
- reviewer note、feedback 和业务 metadata 作用不同，不能互相替代。

## 六、组件边界

LangSmith 把能力分为几层：

- Instrumentation：SDK、框架封装、OTel 或 REST 负责产生 runs。
- Storage/query：project、trace、thread、feedback 与用量数据。
- Investigation：Trace UI、筛选、搜索、Chat 和 Insights。
- Monitoring：dashboard、alert、rules 与 online evaluation。
- Prompt/Context：可版本化的非代码行为资产。
- Gateway：统一模型入口和策略控制，但会产生独立 gateway trace。

这几层有关联但不自动等价。例如 Gateway 的模型调用 trace 当前不能自动成为应用 trace 的子节点；模型配置也不等于运行时已经使用该模型。

## 七、保留期与文档口径

官方页面存在两种口径：

- 概念页写 SaaS trace 保留 180 天。
- 快速开始示例提到 Developer 计划保留 14 天。

应把计划、区域、短期/长期保留层和组织配置视为最终事实来源。上线前在当前 workspace 的 Usage/Retention 设置中核验，不能把教程示例当合同条款。

## 八、生产建模建议

推荐统一根 run metadata：

| 字段 | 用途 |
|---|---|
| environment | prod、staging 等环境隔离 |
| app_version / release | 回归定位 |
| tenant_id_hash | 租户切片；避免直接写敏感标识 |
| route / feature | 业务入口 |
| thread_id | 跨 trace 会话关联 |
| request_id | 与应用日志关联 |
| experiment / feature_flag | 灰度和对照 |

推荐 project 命名：<code>系统-能力-环境</code>，例如 <code>horse-ai-chat-prod</code>。project 不应高基数到每用户一个，也不应把生产与测试混在同一 project 后再靠过滤补救。

## 九、排障顺序

1. 查 root run 是否存在、project 是否正确。
2. 用 Details 看输入输出和错误是否完整。
3. 检查父子 ID、dotted order、时间和 thread ID。
4. 检查 LLM run type、消息格式、model/provider 和 usage metadata。
5. 再看 Messages/Waterfall 是否只是派生展示问题。
6. 最后核对采样、脱敏、组织限额、保留期和异步 flush。