核心概念
本页深入介绍 Litefuse 是如何组织和捕获数据的。理解这些概念会让调试和处理 trace 更轻松。
准备好开始了？查看 快速开始指南 上报你的第一个 trace。
Observation、Trace 与会话
Litefuse 把应用数据组织成三个核心概念：observation、trace 和会话。
Observation
Observation 是 trace 中的单个步骤。Litefuse 支持多种面向 LLM 应用的 observation 类型，例如 generation、toolcall、RAG 检索步骤 等。
Observation 之间可以嵌套。下面的示例展示了一个包含嵌套 observation 的 trace。
Litefuse 中 observation 的层级结构
Litefuse UI 中的 trace 示例
Trace
一个 trace 通常代表一次请求或一次操作。
比如用户向聊天机器人提了一个问题，从用户提问到机器人响应这一整次交互会被记录为一个 trace。
它充当 observation 的容器。user_id、session_id、tags、metadata 等 trace 属性会传播到该 trace 内的所有 observation 上。
会话
trace 还可以选择性地归入 会话。 会话用于把属于同一次用户交互的 trace 聚合起来。 一个常见的例子就是聊天界面里的一个对话线程。
会话可选地聚合 trace
Litefuse UI 中的会话示例
对于多轮对话或多步工作流的应用，建议使用会话。请参考 会话 文档来为 trace 添加会话。
添加属性
把数据组织成 trace 与 observation 后，你还可以添加额外属性来丰富它们。这些属性就像标签，方便你按特定使用场景过滤、分段和分析 trace。
可添加的属性类型有：
| 属性 | 描述 |
|---|---|
| 环境 | 区分来自不同部署环境的数据，例如 production、staging 或 development |
| 标签 | 灵活的标签，用于按功能、API 端点或工作流对 trace 分类 |
| 用户 | 跟踪是哪位终端用户触发了每个 trace |
| 元数据 | 灵活的键值存储，用于自定义信息 |
| 发布与版本 | 跟踪应用版本和组件变更 |
Litefuse 如何捕获数据
理解了数据模型之后，我们再看 Litefuse 实际是如何捕获并处理 trace 的。
基于 OpenTelemetry 构建
Litefuse 基于 OpenTelemetry 构建，这是一个用于从应用中采集遥测数据的开放标准。
这意味着你不会被锁死在 Litefuse 专属 SDK 上。你也可以同时把 trace 发送到多个目标，比如把 LLM 可观测性数据发到 Litefuse，把基础设施监控数据发到 Datadog。
详见 OpenTelemetry 集成指南，了解如何把 OpenTelemetry 与 Litefuse 集成。
Instrumentation
Instrumentation 指通过添加代码来记录其行为的过程。一旦开启了这种记录，Litefuse（通过 OpenTelemetry）就能自动捕获这些事件并组织成 trace 与 observation。
快速开始指南 会带你完成给应用中某个函数接入埋点的整个过程。
后台处理
为了不拖慢应用，Litefuse 不会在 trace 创建时同步发送。 而是把 trace 在本地批量缓存，再在后台发送，让应用始终保持高响应性。
长时运行的应用
上述方式对长时运行的应用（例如 Web 服务器或 API）效果很好，因为后台 exporter 会持续运行，有充足时间自行刷新批次。
短时运行的应用
对于启动后执行某些任务、然后快速退出的短时应用，存在进程结束时队列里仍有未发送 trace 的风险。
为避免数据丢失，短时运行的应用 必须在退出前显式调用 flush()。这会强制 exporter 立即发送所有缓存的 trace，确保进程结束时不会丢数据。