跳到主要内容

Studio Observability

Studio 包含以下 Observability 视图：

  • 指标：查看聚合性能数据
  • Trace：检查单个请求
  • 日志：浏览内部日志和应用日志

这些视图都需要配置 Observability Storage 后端。

快速入门
快速入门的直接链接

有关详细说明，请参阅 Observability 文档。如需快速开始，请将 @mastra/observability 包添加到项目中，并配置 LibSQL 和 DuckDB，建立同时支持 Trace 和指标的本地开发环境。

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

如需跨项目和部署查看托管的 Trace、日志与指标，请参阅 Mastra platform 上的 Observability。

指标
指标的直接链接

指标仪表板会汇总可配置时间范围内（最近 24 小时到 30 天）的 Agent、Workflow 和 Tool 性能。顶行显示 Agent 总运行次数、模型成本、token 消耗和 Scorer 平均表现。下方的详细卡片会进一步展示各模型的使用量和成本、各 Agent 的 token 使用量、token 使用量随时间的变化及预估成本、已完成和错误数量对应的 Trace 量、延迟百分位数（p50 和 p95），以及 Scorer 随时间变化的趋势。

有关更多详情，请参阅指标概述。

备注

指标需要单独的 OLAP Store 来存储 Observability 数据。PostgreSQL、LibSQL 等关系型数据库不支持指标。内存 Storage 会在重启时重置。

Trace
Trace的直接链接

运行 Agent 或 Workflow 时，Observability 标签页会显示 Trace，突出展示模型调用、Tool 执行和 Workflow 步骤等关键 AI 操作。沿着这些 Trace，可以了解数据如何流动、时间花在哪里，以及底层发生了什么。

在 Trace 列表上方打开 Columns，即可显示或隐藏输入、实体、持续时间、输入 token、输出 token、预估成本和自定义 metadata 列。若要显示自定义 metadata，请添加 tracingOptions.metadata 使用的顶层键。Studio 会按当前 Mastra Server 和 API 前缀将所选列保存在浏览器存储中。

Token 和预估成本列需要支持指标的 Observability Store。Branches 视图会隐藏这些列，因为多个 branch 行可能属于同一条 Trace。

Tracing 会过滤底层框架细节，使 Trace 保持聚焦且易于阅读。有关更多详情，请参阅 Tracing 概述。

若要导出 Trace，请在 Trace 面板标题栏中选择 Download trace JSON。这会将完整 Trace 保存为 trace-<id>.json 文件，其中包含每个 span 及其完整输入、输出、metadata 和 attribute。你可以用它共享 Trace、将其附加到错误报告，或离线构建评估数据集。

日志
日志的直接链接

浏览转发到 Observability Storage 的 Mastra 内部日志。日志支持全文搜索（涵盖消息内容、实体名称和 Trace ID）、日期预设（最近 24 小时到 30 天），以及按级别、实体类型和实体名称进行多选筛选。选择日志后会打开详情面板，其中显示完整消息、结构化数据和 metadata。如果日志与 Trace 相关联，可以直接转到相应 Trace 和 span 时间线。

配置 Observability 后，默认会启用日志转发。有关日志级别配置、查询示例和自定义详情，请参阅日志记录。

On this page