Agent监测-Langfuse核心概念

Trace（一次完整任务）
│
├── Span：Turn-1
│   │
│   ├── Generation
│   │   ├── Model: GPT-4o
│   │   ├── Prompt
│   │   ├── Output
│   │   ├── Input Tokens
│   │   ├── Output Tokens
│   │   └── Cost
│   │
│   └── Span：Tool Use (LS)
│       ├── Event: tool_start
│       ├── Event: command_execute
│       └── Event: success
│
├── Span：Turn-2
│   │
│   ├── Generation
│   │   ├── Prompt
│   │   └── Output
│   │
│   └── Span：Tool Use (Read)
│       ├── Event: file_open
│       ├── Event: retry
│       └── Event: success
│
├── Span：Turn-3
│   │
│   ├── Generation
│   └── Span：Tool Use (Edit)
│
└── Span：Final Answer

Trace：一次完整任务

Trace 表示一次完整的 Agent 执行过程。

用户提问
 ↓
Agent 思考
 ↓
工具调用
 ↓
生成答案

整个链路对应一个 Trace。

Span：任务中的一个步骤

Span 是 Trace 中的具体执行节点，例如：

Read 文件
Search 搜索
Bash 执行命令

通过 Span 可以分析每个步骤的耗时和执行情况。

Event：步骤中的关键事件

Event 是 Span 内部发生的瞬时事件。

例如：

Span(Read)

├── file_open
├── retry
└── success

常用于记录重试、异常和关键决策。

Generation：一次 LLM 调用

Generation 是 Langfuse 针对大模型调用扩展的特殊 Span。

除了记录耗时，还会记录：

• Model
• Prompt
• Output
• Token Usage
• Cost

例如：

Trace
├── tool_use:Read
├── Generation
│   ├── model=gpt-4o
│   ├── prompt=...
│   ├── output=...
│   └── tokens=300
└── tool_use:Write

对于 Agent 系统而言，Generation 往往是最重要的观测对象。