Tracing

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

升级后 observability 数据会停止流入

如果将 Mastra 包升级到 v1，却没有将 telemetry: 配置迁移到 observability:，运行时会忽略旧配置。服务可以正常启动且不会报错，但不会向任何位置发送 Trace、日志或 metric。如果此前向 Mastra Cloud 发送数据，控制面板将变为空白。

请在升级 Mastra 包的同一次变更中完成此迁移，并确认 Trace 出现在 Mastra Studio 中，再视为升级完成。如果此前托管在 Mastra Cloud，还需遵循 Mastra Cloud 迁移指南。新平台需要新的访问令牌和 Studio 项目，MastraPlatformExporter 才能向其发送数据。

Exporter 重命名

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

迁移路径
迁移路径的直接链接

从基于 OTEL 的 Telemetry（0.x）迁移
从基于 OTEL 的 Telemetry（0.x）迁移的直接链接

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

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

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）：

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 文档。

迁移后（带自定义配置的 v1）
迁移后（带自定义配置的 v1）的直接链接

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

npm
pnpm
Yarn
Bun

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

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

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

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

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',
              },
            },
          }),
        ],
      },
    },
  }),
})

主要变更：

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

有关所有可用 exporter，请参阅 exporter 文档。

从 AI Tracing 迁移
从 AI Tracing 迁移的直接链接

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

迁移前（AI tracing）：

import { Mastra } from '@mastra/core'

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

迁移后（v1 observability）：

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

主要变更：

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

已变更
已变更的直接链接

包导入路径
包导入路径的直接链接

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

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

npm
pnpm
Yarn
Bun

npm install @mastra/observability@latest

pnpm add @mastra/observability@latest

yarn add @mastra/observability@latest

bun add @mastra/observability@latest

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

Registry 配置
Registry 配置的直接链接

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

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

+ 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`
configuration-property-processors-to-spanoutputprocessors的直接链接

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

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

+ 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-method-exportevent-to-exporttracingevent的直接链接

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

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

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

已移除
已移除的直接链接

基于 OTEL 的 `telemetry` 配置
otel-based-telemetry-configuration的直接链接

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

迁移时，请按照上面的“从基于 OTEL 的 Telemetry（0.x）迁移”部分操作。详细配置选项请参阅 observability tracing 文档。

自定义 instrumentation 文件
自定义 instrumentation 文件的直接链接

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

迁移时，请使用内置 exporter 系统，或通过 ObservabilityExporter 接口实现自定义 exporter。详情请参阅 exporter 文档。

`instrumentation.mjs` 文件
instrumentationmjs-files的直接链接

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

迁移前（0.x）
迁移前（0.x）的直接链接

此前需要 instrumentation 文件：

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

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

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

迁移后（v1）
迁移后（v1）的直接链接

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

// 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 标志，正常启动进程：

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

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

Provider 迁移参考
Provider 迁移参考的直接链接

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

Provider	Exporter	指南	参考
Arize AX, Arize Phoenix	Arize	指南	参考
Braintrust	Braintrust	指南	参考
Langfuse	Langfuse	指南	参考
LangSmith	LangSmith	指南	参考
Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL	OpenTelemetry	指南	参考
LangWatch	<即将推出>	-	-

安装
安装的直接链接

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

npm
pnpm
Yarn
Bun

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

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

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

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

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

npm
pnpm
Yarn
Bun

npm install @mastra/otel-exporter@latest

pnpm add @mastra/otel-exporter@latest

yarn add @mastra/otel-exporter@latest

bun add @mastra/otel-exporter@latest

此外还需安装 Provider 所需的协议包（请参阅 OTEL 指南）。

迁移路径迁移路径的直接链接

从基于 OTEL 的 Telemetry（0.x）迁移从基于 OTEL 的 Telemetry（0.x）迁移的直接链接

迁移后（带自定义配置的 v1）迁移后（带自定义配置的 v1）的直接链接

从 AI Tracing 迁移从 AI Tracing 迁移的直接链接

已变更已变更的直接链接

包导入路径包导入路径的直接链接

Registry 配置Registry 配置的直接链接

配置属性 processors 改为 spanOutputProcessorsconfiguration-property-processors-to-spanoutputprocessors的直接链接

Exporter 方法 exportEvent 改为 exportTracingEventexporter-method-exportevent-to-exporttracingevent的直接链接

已移除已移除的直接链接

基于 OTEL 的 telemetry 配置otel-based-telemetry-configuration的直接链接

自定义 instrumentation 文件自定义 instrumentation 文件的直接链接

instrumentation.mjs 文件instrumentationmjs-files的直接链接

迁移前（0.x）迁移前（0.x）的直接链接

迁移后（v1）迁移后（v1）的直接链接

Provider 迁移参考Provider 迁移参考的直接链接

安装安装的直接链接