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

# Tracing

v1 使用专用的 `@mastra/observability` 包重构了 observability 系统。本指南根据升级来源版本介绍两条迁移路径。

> **升级后 observability 数据会停止流入:** 如果将 Mastra 包升级到 v1，却没有将 `telemetry:` 配置迁移到 `observability:`，运行时会忽略旧配置。服务可以正常启动且不会报错，但**不会向任何位置发送 Trace、日志或 metric**。如果此前向 Mastra Cloud 发送数据，控制面板将变为空白。
>
> 请在升级 Mastra 包的同一次变更中完成此迁移，并确认 Trace 出现在 [Mastra Studio](https://mastra.zisheng.pro/docs/studio/observability) 中，再视为升级完成。如果此前托管在 Mastra Cloud，还需遵循 [Mastra Cloud 迁移指南](https://mastra.zisheng.pro/guides/migrations/mastra-cloud)。新平台需要新的访问令牌和 Studio 项目，`MastraPlatformExporter` 才能向其发送数据。

> **Exporter 重命名:** `MastraPlatformExporter`（向 Mastra 平台发送数据）替代了之前的 `CloudExporter`，`MastraStorageExporter`（将数据持久化到 Mastra Storage）替代了之前的 `DefaultExporter`。原有类仍可从 `@mastra/observability` 获取，行为也保持一致，但已弃用。新代码应使用 `MastraPlatformExporter` 和 `MastraStorageExporter`。现有的 `CloudExporter` 或 `DefaultExporter` 导入在未来主版本移除前仍可继续使用。

## 迁移路径

### 从基于 OTEL 的 Telemetry（0.x）迁移

如果使用 Mastra 中旧的 `telemetry:` 配置，请注意该系统已彻底重新设计。

**迁移前（带 OTEL telemetry 的 0.x）：**

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  telemetry: {
    serviceName: 'my-app',
    enabled: true,
    sampling: {
      type: 'always_on',
    },
    export: {
      type: 'otlp',
      endpoint: 'http://localhost:4318',
    },
  },
})
```

**迁移后（带 observability 的 v1）：**

```typescript
import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  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
        ],
      },
    },
  }),
})
```

此配置包含 `MastraStorageExporter`、`MastraPlatformExporter` 和 `SensitiveDataFilter` Processor。完整配置选项请参阅 [observability tracing 文档](https://mastra.zisheng.pro/docs/observability/tracing/overview)。

#### 迁移后（带自定义配置的 v1）

如需配置特定 exporter（例如 OTLP），请安装 exporter 包并进行配置：

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-app',
        sampling: { type: 'always' },
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: 'http://localhost:4318/v1/traces',
                protocol: 'http/protobuf',
              },
            },
          }),
        ],
      },
    },
  }),
})
```

主要变更：

1. 安装 `@mastra/observability` 包
2. 用 `observability: new Observability()` 替换 `telemetry:`
3. 使用显式的 `configs:`，并配置 `MastraStorageExporter`、`MastraPlatformExporter` 和 `SensitiveDataFilter`
4. 导出类型从字符串字面量（`'otlp'`）改为 exporter 类实例（`new OtelExporter()`）

有关所有可用 exporter，请参阅 [exporter 文档](https://mastra.zisheng.pro/docs/observability/integrations/overview)。

### 从 AI Tracing 迁移

如果已经升级到 AI tracing（中间系统），则需要安装新包并使用显式配置。

**迁移前（AI tracing）：**

```typescript
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  observability: {
    default: { enabled: true },
  },
})
```

**迁移后（v1 observability）：**

```typescript
import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

主要变更：

1. 安装 `@mastra/observability` 包
2. 从 `@mastra/observability` 导入 `Observability`、exporter 和 Processor
3. 使用显式的 `configs`，并配置 `MastraStorageExporter`、`MastraPlatformExporter` 和 `SensitiveDataFilter`

## 已变更

### 包导入路径

observability 功能已迁移到专用的 `@mastra/observability` 包。

迁移时，请安装该包并更新 import 语句：

**npm**:

```bash
npm install @mastra/observability@latest
```

**pnpm**:

```bash
pnpm add @mastra/observability@latest
```

**Yarn**:

```bash
yarn add @mastra/observability@latest
```

**Bun**:

```bash
bun add @mastra/observability@latest
```

```diff
- import { Tracing } from '@mastra/core/observability';
+ import { Observability } from '@mastra/observability';
```

### Registry 配置

observability registry 现在使用带显式配置的 `Observability` 类实例进行配置，而不再使用普通对象。

迁移时，请使用带显式 exporter 和 Processor 的 `new Observability()`。

```diff
+ import {
+   Observability,
+   MastraStorageExporter,
+   MastraPlatformExporter,
+   SensitiveDataFilter,
+ } from '@mastra/observability';

  export const mastra = new Mastra({
-   observability: {
-     default: { enabled: true },
-   },
+   observability: new Observability({
+     configs: {
+       default: {
+         serviceName: 'mastra',
+         exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
+         spanOutputProcessors: [new SensitiveDataFilter()],
+       },
+     },
+   }),
  });
```

### 配置属性 `processors` 改为 `spanOutputProcessors`

span Processor 的配置属性已从 `processors` 重命名为 `spanOutputProcessors`。

迁移时，请在配置对象中重命名该属性。

```diff
+ import { SensitiveDataFilter } from '@mastra/observability';

  export const mastra = new Mastra({
    observability: new Observability({
      configs: {
        production: {
          serviceName: 'my-app',
-         processors: [new SensitiveDataFilter()],
+         spanOutputProcessors: [new SensitiveDataFilter()],
          exporters: [...],
        },
      },
    }),
  });
```

### Exporter 方法 `exportEvent` 改为 `exportTracingEvent`

如果构建了自定义 exporter，请将 exporter 方法从 `exportEvent` 重命名为 `exportTracingEvent`。

迁移时，请更新自定义 exporter 中的方法实现。

```diff
export class MyExporter implements ObservabilityExporter {
-   exportEvent(event: TracingEvent): void {
+   exportTracingEvent(event: TracingEvent): void {
      // export logic
    }
  }
```

## 已移除

### 基于 OTEL 的 `telemetry` 配置

0.x 中基于 OTEL 的 `telemetry` 配置已移除。不再支持使用 `serviceName`、`sampling.type` 和 `export.type` 属性的旧系统。

迁移时，请按照上面的“从基于 OTEL 的 Telemetry（0.x）迁移”部分操作。详细配置选项请参阅 [observability tracing 文档](https://mastra.zisheng.pro/docs/observability/tracing/overview)。

### 自定义 instrumentation 文件

已移除对 `/mastra` 中 instrumentation 文件（扩展名为 `.ts`、`.js` 或 `.mjs`）的自动检测。不再支持通过独立文件提供自定义 instrumentation。

迁移时，请使用内置 exporter 系统，或通过 `ObservabilityExporter` 接口实现自定义 exporter。详情请参阅 [exporter 文档](https://mastra.zisheng.pro/docs/observability/integrations/overview)。

### `instrumentation.mjs` 文件

如果此前使用 `instrumentation.mjs` 文件初始化 OpenTelemetry instrumentation（常见于 AWS Lambda 等部署配置），现在不再需要这些文件。新的 observability 系统直接在 Mastra 实例中配置。

#### 迁移前（0.x）

此前需要 instrumentation 文件：

```javascript
// instrumentation.mjs
import { NodeSDK } from '@opentelemetry/sdk-node'
// ... OTEL setup
```

并且必须在启动进程时导入：

```bash
node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
```

#### 迁移后（v1）

只需移除 `instrumentation.mjs` 文件，并在 Mastra 实例中配置 observability：

```typescript
// src/mastra/index.ts
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

不使用 `--import` 标志，正常启动进程：

```bash
node --env-file=".env" .mastra/output/index.mjs
```

无需独立的 instrumentation 文件或特殊启动标志。

## Provider 迁移参考

如果在 0.x 中使用基于 OTEL 的 telemetry 和特定 Provider，请按下表在 v1 中进行配置：

| Provider                                                  | Exporter          | 指南                                                                                    | 参考                                                                                    |
| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Arize AX, Arize Phoenix                                   | **Arize**         | [指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/arize)      | [参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                | **Braintrust**    | [指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/braintrust) | [参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                  | **Langfuse**      | [指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/langfuse)   | [参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                 | **LangSmith**     | [指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/langsmith)  | [参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel)       | [参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/otel)       |
| LangWatch                                                 | <即将推出>            | -                                                                                     | -                                                                                     |

### 安装

**专用 exporter**（Arize、Braintrust、Langfuse、LangSmith）：

**npm**:

```bash
npm install @mastra/[exporter-name]-exporter
```

**pnpm**:

```bash
pnpm add @mastra/[exporter-name]-exporter
```

**Yarn**:

```bash
yarn add @mastra/[exporter-name]-exporter
```

**Bun**:

```bash
bun add @mastra/[exporter-name]-exporter
```

**OpenTelemetry exporter**（Dash0、Laminar、New Relic、SigNoz、Traceloop）：

**npm**:

```bash
npm install @mastra/otel-exporter@latest
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest
```

此外还需安装 Provider 所需的协议包（请参阅 [OTEL 指南](https://mastra.zisheng.pro/docs/observability/integrations/exporters/otel)）。