> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Studio Observability

Studio 包含以下 Observability 视图：

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

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

## 快速入门

有关详细说明，请参阅 [Observability 文档](https://mastra.zisheng.pro/docs/observability/overview)。如需快速开始，请将 `@mastra/observability` 包添加到项目中，并配置 [LibSQL](https://mastra.zisheng.pro/reference/storage/libsql) 和 [DuckDB](https://mastra.zisheng.pro/reference/vectors/duckdb)，建立同时支持 Trace 和指标的本地开发环境。

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

```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

如需跨项目和部署查看托管的 Trace、日志与指标，请参阅 [Mastra platform 上的 Observability](https://mastra.zisheng.pro/docs/mastra-platform/observability)。

## 指标

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

有关更多详情，请参阅[指标概述](https://mastra.zisheng.pro/docs/observability/metrics/overview)。

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

## 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 概述](https://mastra.zisheng.pro/docs/observability/tracing/overview)。

若要导出 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 后，默认会启用日志转发。有关日志级别配置、查询示例和自定义详情，请参阅[日志记录](https://mastra.zisheng.pro/docs/observability/logging)。

## 相关内容

- [Observability 概述](https://mastra.zisheng.pro/docs/observability/overview)
- [指标概述](https://mastra.zisheng.pro/docs/observability/metrics/overview)
- [Tracing 概述](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [日志记录](https://mastra.zisheng.pro/docs/observability/logging)
- [Mastra platform Observability](https://mastra.zisheng.pro/docs/mastra-platform/observability)