跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

Studio 可观测性

Studio 包含以下可观测性视图：

  • Metrics 用于聚合性能数据
  • Traces 用于检查单个请求
  • Logs 用于浏览内部日志和应用日志

所有这些都需要配置一个可观测性存储后端。

快速开始
快速开始的直接链接

如需详细说明，请遵循可观测性指南。要快速上手，请将 @mastra/observability 包添加到你的项目，并配合 LibSQL 和 DuckDB 进行配置，以获得一个同时支持 traces 和 metrics 的本地开发环境。

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

然后将以下内容添加到你的 src/mastra/index.ts：

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 platform
Mastra platform的直接链接

如需跨项目和部署的托管 traces、logs 和 metrics，参见 Mastra platform 上的可观测性。

Metrics
Metrics的直接链接

一个仪表盘，用于在可配置的时间范围（最近 24 小时到 30 天）内汇总 agent、workflow 和 tool 的性能。顶部一行显示 agent 运行总数、模型成本、token 消耗和平均 scorer 表现。下方详细卡片分解了每个模型的模型使用量和成本、每个 agent 的 token 使用量、随时间的 token 使用量及预估成本、完成和错误计数的 trace 量、延迟百分位数（p50 和 p95），以及随时间的 scorer 趋势。

更多详情请访问 metrics 概览。

备注

Metrics 需要支持它们的可观测性存储，例如 DuckDB、ClickHouse，或启用了 observability 域的 PostgresStoreVNext。LibSQL、MSSQL 和 MongoDB 不支持 metrics。内存存储在重启后会重置。完整列表参见存储支持。

Traces
Traces的直接链接

当你运行 agent 或 workflow 时，Observability 标签页会显示突出关键 AI 操作的 traces，例如模型调用、tool 执行和 workflow 步骤。跟随这些 traces，可以查看数据如何流动、时间花在哪里，以及底层发生了什么。

在 trace 列表上方，打开 Columns 可以显示或隐藏 input、entity、duration、input token、output token、预估成本和自定义 metadata 列。要显示自定义 metadata，请添加 tracingOptions.metadata 中使用的顶层 key。Studio 会针对当前 Mastra 服务器和 API 前缀将选择保存在浏览器存储中。

Token 和预估成本列需要支持 metrics 的可观测性存储。这些列在 Branches 视图中保持隐藏，因为多行 branch 可能属于同一个 trace。

Tracing 会过滤掉底层框架细节，让你的 traces 保持聚焦和可读。更多详情请访问 traces 用法。

要导出 trace，请在 trace 面板标题中选择 Download trace JSON。这会将整个 trace 保存为 trace-<id>.json 文件，包含每个 span 及其完整的 input、output、metadata 和 attributes。用它来分享 trace 或附加到 bug 报告中，或者离线构建评估数据集。

Logs
Logs的直接链接

浏览转发到你的可观测性存储的 Mastra 内部日志。Logs 提供跨消息内容和实体名称（包括 trace ID）的全文搜索。日期预设范围从最近 24 小时到 30 天。多选过滤器涵盖 level 和实体类型，以及实体名称。选择一条日志会打开详情面板，显示完整消息、结构化数据和 metadata。如果该日志与某个 trace 关联，你可以直接跳转到 trace 和 span 时间线。

配置可观测性时，日志转发默认启用。关于级别配置、查询示例和自定义详细信息，参见日志。

On this page