第22章 追踪（Traces）——Mastra 可观测性入门

可观测性 Mastra 的可观测性系统让你能看清每一次 agent 运行、workflow 步骤、工具调用和模型交互。agent 的行为取决于模型响应、提示词、工具、记忆和 workflow 状态，因此可观测性可以帮助你从一开始就检查运行时的决策过程。 先从与 trace 关联的几个页面入手： Usage（用量）：查看某次执行的 span 层级结构、输入输出、token 用量、耗时和 trace 上下文。 Logging（日志）：将应用和 Mastra 内部产生的结构化日志条目汇聚起来，并自动关联到对应的 trace。 Feedback（反馈）：存储评分、评论、纠错等人工审查信号，并与 trace 和 span 建立关联。 Storage（存储）：为持久化 trace、日志、指标聚合和反馈查询选择后端。 使用 Metrics 分析由 span 推导出的聚合用量、性能和成本数据，无需额外的埋点。通过 Configuration 可以启用应用所需的信号类型和导出器。 何时使用可观测性 agent 出现异常行为时，通过完整的决策路径、工具调用和模型响应来排查问题。 监控 agent、workflow 和工具的延迟，找出性能瓶颈。 长期跟踪 token 消耗和预估成本，控制开支。 通过追踪每个步骤的执行过程来诊断 workflow 失败。 对比修改提示词或更换模型前后 agent 的性能表现。 各组件如何协同 配置好可观测性之后，每次 agent 运行、workflow 执行、工具调用和模型交互都会产生一个 span。Mastra 会把相关的 span 组织成 trace，以层级时间线的形式展示请求的完整生命周期。 span 结束时，Mastra 无需任何额外代码即可提取耗时、token 数量和成本估算。这些指标为 Studio 中的聚合仪表盘提供数据支撑。 在 trace 上下文中，所有 logger.info()、logger.warn()、logger.error() 调用都会打上当前的 trace 和 span ID 标签，你可以从一条日志直接跳转到产生它的 trace。 Feedback 用于记录评分、评论、纠错等人工审查信号。这些反馈可以关联到 trace 和 span，并通过与指标相同的可观测性存储进行查询。 这些记录共享 trace ID、span ID、实体类型、实体名称等关联字段，你可以借助它们从指标异常点追溯到对应的 trace、日志和相关反馈。 快速上手 安装 @mastra/observability 以及支持 trace 和指标的存储后端： npmpnpmYarnBunnpm install @mastra/observability @mastra/libsql @mastra/duckdb
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
bun add @mastra/observability @mastra/libsql @mastra/duckdb
然后在 Mastra 实例中配置可观测性。下面的例子使用组合存储，把可观测性数据路由到 DuckDB（支持指标聚合），其余数据仍保存在 LibSQL 中： src/mastra/index.tsimport { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
Observability,
MastraStorageExporter,
MastraPlatformExporter,
SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
storage: new MastraCompositeStore({
id: 'composite-storage',
default: new LibSQLStore({
id: 'mastra-storage',
url: 'file:./mastra.db',
}),
domains: {
observability: await new DuckDBStore().getStore('observability'),
},
}),
observability: new Observability({
configs: {
default: {
serviceName: 'mastra',
exporters: [
new MastraStorageExporter(), // 将可观测性事件持久化到 Mastra Storage
new MastraPlatformExporter(), // 将可观测性事件发送到 Mastra 平台（需设置 MASTRA_PLATFORM_ACCESS_TOKEN）
],
spanOutputProcessors: [
new SensitiveDataFilter(), // 脱敏处理密码、令牌、密钥等敏感数据
],
},
},
}),
})
它支持链路追踪、日志转发和指标收集。Mastra 还支持 Langfuse、Datadog 等外部追踪服务，以及任何兼容 OpenTelemetry 的平台。如果要在向外部服务发送数据的同时保留 Mastra Studio 的访问能力，请参阅 Maintaining Studio access 部分。 配置（Direct link to Configuration） 可观测性只需在 Mastra 实例上配置一次，即可同时应用于链路追踪、日志和指标。 基础配置（Direct link to Basic config） 一份可观测性配置通常包含： serviceName：附加到导出的可观测性数据上的服务标识。 exporters：一个或多个链路、日志和派生指标的目标导出目的地。 spanOutputProcessors：在 span 导出前执行的转换处理。 保持 Studio 访问能力（Direct link to Maintaining Studio access） 添加外部 exporter 时，请保留 MastraStorageExporter（用于 Studio 可观测性）和/或 MastraPlatformExporter（用于托管版 Mastra 平台的可观测性）。 下面的示例只展示了可观测性配置部分，存储需要单独配置。 src/mastra/observability.tsimport { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
configs: {
production: {
serviceName: 'my-service',
exporters: [
new ArizeExporter({
endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
apiKey: process.env.PHOENIX_API_KEY,
}),
new MastraStorageExporter(),
new MastraPlatformExporter(),
],
},
},
})
在 serverless 环境中刷新数据（Direct link to Flushing in serverless environments） 在 serverless 环境中，需要在运行时暂停或退出前刷新可观测性 exporter 的数据： await mastra.observability.flush()
在 serverless 环境中请使用外部存储，而不是本地文件存储。存储的选择与路由请参阅 Storage 部分。 多配置设置（Direct link to Multi-config setup） 当不同环境或不同请求类型需要不同的 exporter 或采样策略时，可以使用多份配置，并通过 configSelector 在运行时选择生效的配置。 src/mastra/index.tsimport { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
```typescript const langfuseExporter = new LangfuseExporter() export const mastra = new Mastra({ observability: new Observability({ configs: { development: { serviceName: 'my-service-dev', exporters: [storageExporter], }, production: { serviceName: 'my-service-prod', exporters: [storageExporter, langfuseExporter], }, }, configSelector: () => process.env.NODE_ENV || 'development', }), }) ```

关于 trace 采样，参见 Tracing。

存储

存储决定了哪些可观测性信号能持久化、哪些查询可用、指标聚合是否能正常工作。请使用专门的可观测性存储，而不是复用主应用存储。

信号支持

存储支持因信号和工作负载而异。MastraStorageExporter 可以将 traces 持久化到 ClickHouse、PostgreSQL、MSSQL、MongoDB 和 LibSQL。指标则需要有分析能力的存储：

• DuckDB：适合本地测试和开发。
• ClickHouse：适合高流量的生产环境可观测性。
• PostgresStoreVNext：启用 observability domain 后支持指标。务必传入时间范围，避免全分区扫描。
• Mastra platform：使用 MastraPlatformExporter 获得托管式可观测性，无需自己维护后端。

完整的 provider 列表和支持的 tracing 策略，参见 Mastra Storage exporter。当主存储不支持可观测性，或工作负载需要独立扩缩容时，可以用 composite storage 把 observability domain 单独路由出去。

本地开发

本地开发推荐这样配置：

• LibSQLStore 作为主应用存储
• DuckDBStore 用于 observability domain
• MastraStorageExporter 用于本地访问 Studio

生产部署

可观测性流量的写入压力通常比应用其他部分大得多。生产环境中：

• 如果自己维护可观测性存储，为 observability domain 使用 MastraStorageExporter 搭配 ClickHouse。
• 如果不想自己管后端，用 MastraPlatformExporter 使用托管在 Mastra platform 上的可观测性。
• 当可观测性需要与主应用数据不同的后端或扩缩容策略时，使用 composite storage。

后端兼容性细节和 exporter 的批处理行为，参见 Mastra Storage exporter。

Mastra platform

想要跨项目、跨部署的托管式 traces、日志和指标，参见 Mastra platform 上的 Observability。

下一步

• Tracing
• Logging
• Metrics
• Feedback
• Mastra Studio
• Automatic metrics reference
• Mastra platform observability