主题
可观测性概念
LangSmith 如何把可观测性数据组织成运行、追踪、线程与轨迹，以及如何发送追踪。
LangSmith 可观测性让你记录、查看并分析 AI 智能体走过的每一步。本页说明这些数据在 LangSmith 中如何被组织与可视化，以及如何开始发送追踪。
LangSmith 如何组织并可视化数据
在 LangSmith 中，智能体执行的每一个工作单元——一次模型调用、一次工具调用或一次信息检索——都会被记录为一个 运行。单次操作产生的那些运行会被汇集进一条 追踪。多轮会话中的追踪还可以串联起来，形成一条 线程。
轨迹 是组织并可视化这些数据的另一种方式：线程把一次会话的追踪归为一组并保留它们的嵌套结构，而轨迹把整次会话摊平成一个有序的消息列表，展示智能体从头到尾走过的路径。
运行
运行 表示智能体执行的一个工作单元，例如调用 LLM、格式化提示词或检索文档。如果你熟悉 OpenTelemetry，可以把运行理解为一个跨度（span）。
追踪
追踪 是单次操作产生的所有运行的集合。例如，一个用户请求触发的智能体先调用模型、再运行工具、随后又调用一次模型，这些运行都属于同一条追踪。运行通过唯一的 trace ID 绑定到追踪上。
NOTE
每条追踪最多包含 25,000 个运行。一旦达到该上限，LangSmith 就会拒收你为该追踪发送的任何额外运行。
线程
线程 表示一次多轮会话的一系列追踪。一轮（turn）就是这次会话中的一次交互：用户的一条消息加上智能体为此做的一切。每一轮都会被记录成独立的一条追踪。要把追踪归入某个线程，需传入一个 thread_id 元数据键并赋予唯一值。
了解如何配置线程。
轨迹
轨迹 是一个摊平的有序消息列表，展示智能体从头到尾走过的路径。
在 LangSmith 中，轨迹是对一个线程内所有追踪的一次投影。它包含会话过程中交换的人类、AI 与工具消息，每条消息只出现一次、按首次出现的顺序排列，并去掉运行之间的嵌套结构。
了解轨迹在 Trajectory 视图中如何呈现。
对比追踪、线程与轨迹
| 追踪 | 线程 | 轨迹 | |
|---|---|---|---|
| 形态 | 运行的树 | 追踪的序列 | 摊平的有序消息列表 |
| 包含内容 | 每个运行，含完整的输入与输出 | 每条关联追踪里的所有运行 | 每条关联追踪里的所有消息（去重） |
| 何时用它 | 你在排查某一次操作为何失败或变慢 | 你要查看智能体跨多轮的表现，并保留时序与嵌套 | 你只想读会话里交换了什么，不需要执行细节 |
INFO
用 Chat 来分析追踪、运行与线程。Chat 帮你理解智能体表现、排查问题，并从会话线程中获得洞察，而不必手动翻查数据。
项目
项目 是某个应用或服务相关的全部追踪的容器。
追踪增强
反馈
反馈 让你按特定标准给单个运行打分。每条反馈由一个标签和一个得分组成，通过唯一的 run ID 绑定到某个运行上。反馈可以是连续值或离散值（分类型），标签可以在同一组织内的多个运行之间复用。
关于反馈如何存储，参见反馈数据格式指南。
标签
标签 是可以附加到运行上的字符串，用于在 LangSmith UI 中对运行分类、过滤和分组。
了解如何给追踪附加标签。
元数据
元数据 是你附加到运行上的一组键值对，例如应用版本、运行环境或其他上下文信息。与标签一样，你可以用元数据来过滤和分组运行。
了解如何给追踪添加元数据。
发送追踪
向 LangSmith 发送追踪数据有两种方式。
集成
LangSmith 的集成为主流 LLM 服务商与智能体框架提供自动追踪（相当于通用可观测性里的自动埋点）。当你使用 LangChain、LangGraph、OpenAI、Anthropic、CrewAI 等受支持的框架时，集成会自动采集输入、输出与元数据，无需改动代码。
手动埋点
手动埋点 让你给任意代码加上追踪，与所用框架无关。当你没有使用受支持的集成，或者需要精细控制追踪哪些内容时，就用它。LangSmith 提供三种机制：
@traceable/traceable：装饰器，用来追踪任意函数trace上下文管理器（Python）：包裹指定的代码块RunTreeAPI：底层、显式地构造追踪
了解如何添加手动埋点。
数据保留
LangSmith（SaaS）自摄入起保留追踪数据 180 天。之后追踪会被永久删除，仅保留少量元数据用于用量统计。保留档位与定价的详情见用量与计费：数据保留。
NOTE
若要在保留期之后继续保存数据，请把它加入数据集。即使源追踪已被删除，数据集也会无限期保留。
要在到期前删除追踪，参见管理追踪。