追踪

🌐 Tracing

在 v1 中，可观测性系统已被重构，并引入了专用的 @mastra/observability 包。本指南涵盖了两种迁移路径，具体取决于你要升级的版本。

🌐 The observability system has been restructured in v1 with a dedicated @mastra/observability package. This guide covers two migration paths depending on which version you're upgrading from.

迁移路径
Direct link to 迁移路径

🌐 Migration Paths

基于 OTEL 的遥测 (0.x)
Direct link to 基于 OTEL 的遥测 (0.x)

🌐 From OTEL-based Telemetry (0.x)

如果你在 Mastra 中使用旧的 telemetry: 配置，系统已经被完全重新设计。

🌐 If you're using the old telemetry: configuration in Mastra, the system has been completely redesigned.

以前（0.x 版本，使用 OTEL 遥测）：

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

在（v1 带可观测性）之后：

import { Mastra } from '@mastra/core';
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability';

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new DefaultExporter(), // Persists traces to storage for Mastra Studio
          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
});

此配置包括 DefaultExporter、CloudExporter 和 SensitiveDataFilter 处理器。有关完整的配置选项，请参阅可观察性追踪文档。

🌐 This configuration includes DefaultExporter, CloudExporter, and SensitiveDataFilter processor. See the observability tracing documentation for full configuration options.

在（使用自定义配置的 v1 之后）：

如果你需要配置特定的导出器（例如 OTLP），请安装导出器包并进行配置：

🌐 If you need to configure specific exporters (like OTLP), install the exporter package and configure it:

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

主要变化：

🌐 Key changes:

安装 @mastra/observability 包
将 telemetry: 替换为 observability: new Observability()
将显式 configs: 与 DefaultExporter、CloudExporter 和 SensitiveDataFilter 一起使用
导出类型从字符串字面量（'otlp'）变为导出器类实例（new OtelExporter()）

请参阅导出器文档了解所有可用的导出器。

🌐 See the exporters documentation for all available exporters.

由 AI 跟踪
Direct link to 由 AI 跟踪

🌐 From AI Tracing

如果你已经升级到 AI 跟踪（中间系统），你需要安装新软件包并使用明确的配置。

🌐 If you already upgraded to AI tracing (the intermediate system), you need to install the new package and use the explicit configuration.

之前（AI 跟踪）：

import { Mastra } from '@mastra/core';

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

在（v1 可观察性）之后：

import { Mastra } from '@mastra/core';
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability';

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new DefaultExporter(),
          new CloudExporter(),
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(),
        ],
      },
    },
  }),
});

主要变化：

🌐 Key changes:

安装 @mastra/observability 包
从 @mastra/observability 导入 Observability、导出商和处理器
将显式 configs 与 DefaultExporter、CloudExporter 和 SensitiveDataFilter 一起使用

已更改
Direct link to 已更改

🌐 Changed

包导入路径
Direct link to 包导入路径

🌐 Package import path

可观测性功能已移至专用的 @mastra/observability 包。

🌐 The observability functionality has moved to a dedicated @mastra/observability package.

要迁移，请安装该软件包并更新你的导入语句：

🌐 To migrate, install the package and update your import statements:

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';

注册表配置
Direct link to 注册表配置

🌐 Registry configuration

可观测性注册表现在使用带有明确配置的 Observability 类实例进行配置，而不是使用普通对象。

🌐 The observability registry is now configured using an Observability class instance with explicit configs instead of a plain object.

要迁移，请使用 new Observability() 并指定导出器和处理器。

🌐 To migrate, use new Observability() with explicit exporters and processors.

+ import {
+   Observability,
+   DefaultExporter,
+   CloudExporter,
+   SensitiveDataFilter,
+ } from '@mastra/observability';

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

配置属性 `processors` 设置为 `spanOutputProcessors`
Direct link to configuration-property-processors-to-spanoutputprocessors

🌐 Configuration property processors to spanOutputProcessors

跨度处理器的配置属性已从 processors 重命名为 spanOutputProcessors。

🌐 The configuration property for span processors has been renamed from processors to spanOutputProcessors.

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

🌐 To migrate, rename the property in your configuration objects.

+ 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: [...],
        },
      },
    }),
  });

导出方法 `exportEvent` 到 `exportTracingEvent`
Direct link to exporter-method-exportevent-to-exporttracingevent

🌐 Exporter method exportEvent to exportTracingEvent

如果你创建了自定义导出器，导出器方法已从 exportEvent 重命名为 exportTracingEvent。

🌐 If you built custom exporters, the exporter method has been renamed from exportEvent to exportTracingEvent.

要进行迁移，请更新自定义导出器中的方法实现。

🌐 To migrate, update method implementations in custom exporters.

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

已移除
Direct link to 已移除

🌐 Removed

基于 OTEL 的 `telemetry` 配置
Direct link to otel-based-telemetry-configuration

🌐 OTEL-based telemetry configuration

基于 OTEL 的 telemetry 配置在 0.x 版本中已被移除。带有 serviceName、sampling.type 和 export.type 属性的旧系统不再受支持。

🌐 The OTEL-based telemetry configuration from 0.x has been removed. The old system with serviceName, sampling.type, and export.type properties is no longer supported.

要进行迁移，请按照上文“从 OTEL 基于遥测”部分的说明操作。有关详细的配置选项，请参阅可观测性追踪文档。

🌐 To migrate, follow the "From OTEL-based Telemetry" section above. For detailed configuration options, see the observability tracing documentation.

自定义检测文件
Direct link to 自定义检测文件

🌐 Custom instrumentation files

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

🌐 The automatic detection of instrumentation files in /mastra (with .ts, .js, or .mjs extensions) has been removed. Custom instrumentation is no longer supported through separate files.

要进行迁移，请使用内置的导出器系统，或使用 ObservabilityExporter 接口实现自定义导出器。详情请参见导出器文档。

🌐 To migrate, use the built-in exporter system or implement custom exporters using the ObservabilityExporter interface. See the exporters documentation for details.

`instrumentation.mjs` 文件
Direct link to instrumentationmjs-files

🌐 instrumentation.mjs files

如果你以前使用 instrumentation.mjs 文件来初始化 OpenTelemetry 工具（在 AWS Lambda 等部署环境中很常见），现在已经不再需要这些文件。新的可观测性系统可以直接在你的 Mastra 实例中进行配置。

🌐 If you were using instrumentation.mjs files to initialize OpenTelemetry instrumentation (common in deployment setups like AWS Lambda), these are no longer needed. The new observability system is configured directly in your Mastra instance.

之前 (0.x)：

你需要一个仪器文件：

🌐 You needed an instrumentation file:

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

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

🌐 And had to import it when starting your process:

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

在 (v1) 之后:

只需删除 instrumentation.mjs 文件，并在你的 Mastra 实例中配置可观察性：

🌐 Simply remove the instrumentation.mjs file and configure observability in your Mastra instance:

// src/mastra/index.ts
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability';

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new DefaultExporter(), new CloudExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
});

正常启动你的进程，不要使用 --import 标志：

🌐 Start your process normally without the --import flag:

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

无需单独的仪器文件或特殊启动标志。

🌐 No separate instrumentation files or special startup flags required.

提供商迁移参考
Direct link to 提供商迁移参考

🌐 Provider Migration Reference

如果你在 0.x 版本中使用基于 OTEL 的遥测和特定提供商，以下是在 v1 中配置它们的方法：

🌐 If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:

提供商	导出器	指南	参考文献
阿里泽AX，Arize凤凰城	阿里泽	[指南]（/docs/observability/tracing/exporters/arize）	[参考文献]（/reference/observability/tracing/exporters/arize）
Braintrust	Braintrust	[指南]（/docs/observability/tracing/exporters/braintrust）	[参考文献]（/reference/observability/tracing/exporters/braintrust）
Langfuse	引信	[指南]（/docs/observability/tracing/exporters/langfuse）	[参考文献]（/reference/observability/tracing/exporters/langfuse）
兰史密斯	LangSmith	[指南]（/docs/observability/tracing/exporters/langsmith）	[参考文献]（/reference/observability/tracing/exporters/langsmith）
Dash0、Laminar、New Relic、SigNoz、Traceloop、自定义OTEL	OpenTelemetry	[指南]（/docs/observability/tracing/exporters/otel）	[参考文献]（/reference/observability/tracing/exporters/otel）
LangWatch	<coming soon>	-	-

安装
Direct link to 安装

🌐 Installation

专注的导出器（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 导出器（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

以及你提供商所需的协议包（参见 OTEL 指南）。

🌐 Plus the required protocol package for your provider (see OTEL guide).

迁移路径Direct link to 迁移路径

基于 OTEL 的遥测 (0.x)Direct link to 基于 OTEL 的遥测 (0.x)

由 AI 跟踪Direct link to 由 AI 跟踪

已更改Direct link to 已更改

包导入路径Direct link to 包导入路径

注册表配置Direct link to 注册表配置

配置属性 processors 设置为 spanOutputProcessorsDirect link to configuration-property-processors-to-spanoutputprocessors

导出方法 exportEvent 到 exportTracingEventDirect link to exporter-method-exportevent-to-exporttracingevent

已移除Direct link to 已移除

基于 OTEL 的 telemetry 配置Direct link to otel-based-telemetry-configuration

自定义检测文件Direct link to 自定义检测文件

instrumentation.mjs 文件Direct link to instrumentationmjs-files

提供商迁移参考Direct link to 提供商迁移参考

安装Direct link to 安装