📚 编程进阶教程站

第 16 章 · Observability 可观测性 ​

本章目标：掌握 Mastra 的追踪（tracing）、日志与监控体系，能在生产环境定位 Agent 行为异常。

16.1 为什么 Agent 需要可观测性 ​

Agent 的行为取决于提示词、上下文、工具返回值的多重组合——出问题时"看代码"远远不够。Mastra 的可观测系统让你看到每一次运行中的：

  • 每个 agent run、workflow step、tool call、模型交互；
  • 每个环节的输入输出、耗时、token 用量与错误。

这些数据由 Storage 域持久化，可在 Studio 中回放分析。

16.2 启用追踪 ​

typescript
// src/mastra/index.ts
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  agents: { support: supportAgent },
  observability: {
    // 默认导出器把 span 写入配置的 storage，
    // 也可换成 OTLP 导出到 Langfuse/Jaeger 等
    exporters: [
      { type: 'otlp', endpoint: process.env.OTLP_ENDPOINT },
    ],
  },
})

开启后每次调用自动生成 trace 树：

typescript
// 一次 generate 产生的典型 span 层级
// trace: agent.run
//   ├── span: agent.generate          总耗时/token 统计
//   │     ├── span: llm.request       模型请求与响应
//   │     ├── span: tool.execute:search   工具执行详情
//   │     └── span: llm.request       工具结果后的续写请求

16.3 结构化日志 ​

typescript
// src/mastra/logger.ts
import { Logger } from '@mastra/core'

export const logger = new Logger({
  level: 'info',
  // 结构化 JSON 输出便于采集到 ELK/Datadog
})

logger.info('订单查询完成', { orderId: 'A-1001', latencyMs: 320 })

在工具内部打点，让每次执行都有业务上下文：

typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'
import { logger } from '../logger'

export const queryOrder = createTool({
  id: 'query-order',
  description: '按订单号查询状态',
  inputSchema: z.object({ orderId: z.string() }),
  execute: async ({ context }) => {
    logger.info('开始查询订单', { orderId: context.orderId })
    // ...查询逻辑
    return { status: 'shipped' }
  },
})

16.4 生产排障套路 ​

症状排查入口
回答答非所问看 trace 中注入的 system prompt 与检索内容是否正确
工具不触发检查工具 description 是否清晰、schema 是否匹配
延迟飙升按 span 耗时排序，通常是某次 LLM 请求或慢 SQL
成本暴涨追踪 token 字段，检查是否重复注入大段上下文

16.5 监控指标建议 ​

  • 质量类：评估分数（接第 15 章）、用户负反馈率；
  • 性能类：P95 首 token 延迟、每轮平均 token 数；
  • 稳定性：工具错误率、workflow suspend 卡单时长。

本章小结 ​

  • Mastra 自动为 run/step/tool/model 各层生成 trace span 并落存储；
  • 可通过 OTLP 导出到第三方平台（Langfuse/Jaeger 等）；
  • 结构化日志应带业务字段，方便与 trace 关联排障；
  • 排障先看数据：prompt 注入对不对 → 工具描述清不清 → 哪个 span 最慢。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Mastra 可观测系统中一次 agent 调用会产生什么？

2. 想让追踪数据进入 Langfuse 或 Jaeger，应该配置？

3. Agent 从不调用某个工具，最该先检查什么？

4. 生产环境发现成本突然翻倍，最有效的第一步是？

🛠️ 动手实践 ​

  1. 启用追踪后故意给工具写一个模糊的 description，观察 Studio 中工具未被调用的 trace。
  2. 把 OTLP exporter 指向本地 Jaeger，在 UI 里回放一次完整 agent run。
  3. 为三个核心工具补充结构化日志，模拟一次故障并按日志+trace 定位根因。