Observability

Mastra 的可观测性系统让你能够洞察每次 Agent 运行、workflow 步骤、工具调用和模型交互。Agent 行为取决于模型响应、prompts、工具、memory 和 workflow 状态，因此可观测性从第一天起就能帮助你检查运行时决策。

从与 trace 关联的页面开始：

• Usage：检查一次执行的 span 层级、输入、输出、token 用量、耗时和 trace 上下文。
• Logging：转发来自应用和 Mastra 内部的结构化日志条目，并自动与 traces 关联。
• Feedback：存储与 traces 和 spans 关联的评分、评论、修正及其他审核信号。
• Storage：选择用于持久化 traces、日志、指标聚合和反馈查询的后端。

使用 Metrics 分析由 spans 派生的聚合用量、性能和成本数据，无需额外埋点。使用配置启用应用所需的信号和导出器。

何时使用可观测性

• 通过检查完整的决策路径、工具调用和模型响应，调试意外的 Agent 行为。
• 监控 agents、workflows 和工具的延迟，以识别瓶颈。
• 跟踪 token 消耗和估算成本随时间的变化，以控制开支。
• 通过追踪每个步骤的执行情况，诊断 workflow 故障。
• 比较 prompt 或模型变更前后的 Agent 表现。

各部分如何协同

配置可观测性后，每次 Agent 运行、workflow 执行、工具调用和模型交互都会产生一个 span。Mastra 将相关 spans 组织为 traces，以层级时间线的形式展示完整的请求生命周期。

span 结束时，Mastra 无需额外代码即可提取耗时、token 数量和成本估算。这些指标为 Studio 中的聚合仪表盘提供数据。

在已追踪的上下文中，每次 logger.info()、logger.warn() 或 logger.error() 调用都会标记当前的 trace 和 span ID。你可以从日志条目直接跳转到产生它的 trace。

Feedback 记录人工审核信号，例如评分、评论和修正。Feedback 可以关联到 traces 和 spans，并使用与指标相同的可观测性存储进行查询。

这些记录共享关联字段，例如 trace ID、span ID、实体类型和实体名称。你可以借助它们从指标峰值追溯到对应的 traces、日志和相关反馈。

快速开始

安装 @mastra/observability 以及支持 traces 和指标的存储后端：

npm

npm install @mastra/observability @mastra/libsql @mastra/duckdb

pnpm

pnpm add @mastra/observability @mastra/libsql @mastra/duckdb

Yarn

yarn add @mastra/observability @mastra/libsql @mastra/duckdb

Bun

bun add @mastra/observability @mastra/libsql @mastra/duckdb

然后在 Mastra 实例中配置可观测性。以下示例使用组合存储，将可观测性数据路由到 DuckDB（支持指标聚合），其余数据保留在 LibSQL：

src/mastra/index.ts

import { 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(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})

这会启用链路追踪、日志转发和指标。Mastra 还支持 Langfuse、Datadog 等外部追踪提供商，以及任何兼容 OpenTelemetry 的平台。若要在向外部提供商发送数据的同时保留 Mastra Studio 访问能力，参见保持 Studio 访问。

配置

可观测性在 Mastra 实例上配置一次，即适用于 traces、日志和指标。

基础配置

可观测性配置通常包含：

• serviceName：附加到导出的可观测性数据的服务标识符。
• exporters：traces、日志和派生指标的一个或多个目标位置。
• spanOutputProcessors：在 spans 导出之前运行的转换。

保持 Studio 访问

添加外部导出器时，请保留 MastraStorageExporter 以支持 Studio 可观测性，和/或保留 MastraPlatformExporter 以支持托管 Mastra 平台可观测性。

以下示例仅展示可观测性配置。存储需单独配置。

src/mastra/observability.ts

import { 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(),
      ],
    },
  },
})

在无服务器环境中刷新

在无服务器环境中，请在运行时暂停或退出前刷新可观测性导出器：

await mastra.observability.flush()

在无服务器环境中使用外部存储，而不是本地文件存储。关于存储选择和路由，参见存储。

多配置设置

当不同环境或请求类型需要不同的导出器或采样行为时，可使用多个配置。通过 configSelector 在运行时选择生效的配置。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
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 采样，参见链路追踪。

存储

存储决定哪些可观测性信号会被持久化、哪些查询可用，以及指标聚合是否有效。请使用专用的可观测性存储，而不是主应用存储。

信号支持

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

• DuckDB：推荐用于本地测试和开发。
• ClickHouse：推荐用于高吞吐量的生产可观测性。
• PostgresStoreVNext：启用 observability domain 后支持指标。请始终提供时间范围，以避免全分区扫描。
• Mastra 平台：使用 MastraPlatformExporter 获得托管的可观测性，无需自行管理后端。

完整提供商列表和支持的追踪策略，参见 Mastra Storage exporter。当主存储不支持可观测性，或工作负载需要独立扩展时，可使用组合存储将 observability domain 单独路由。

本地开发

本地开发可使用：

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

生产部署

可观测性流量通常比应用其他部分写入更密集。在生产环境中：

• 若在自己的存储中保留可观测性数据，可为 observability domain 使用 MastraStorageExporter 和 ClickHouse。
• 使用 MastraPlatformExporter 获得托管 Mastra 平台可观测性，无需自行管理后端。
• 当可观测性需要与主应用数据不同的后端或扩展策略时，使用组合存储。

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

Mastra 平台

如需跨项目和部署的托管 traces、日志和指标，参见 Mastra 平台上的 Observability。

后续步骤

• 链路追踪
• 日志
• 指标
• 反馈
• Mastra Studio
• 自动指标参考
• Mastra 平台可观测性