云导出器

🌐 Cloud Exporter

CloudExporter 将跟踪发送到 Mastra Cloud 以进行集中监控和团队协作。使用带有有效访问令牌的默认可观察性配置时，它会自动启用。

🌐 The CloudExporter sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.

配置

🌐 Configuration

先决条件

🌐 Prerequisites

1. Mastra 云账户：在 cloud.mastra.ai 注册
2. 访问令牌：在 Mastra Cloud → 设置 → API 令牌 中生成
3. 环境变量：设置你的凭据：

.env

MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx

基础设置

🌐 Basic Setup

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { Observability, CloudExporter } from "@mastra/observability";

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: "my-service",
        exporters: [
          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
        ],
      },
    },
  }),
});

推荐配置

🌐 Recommended Configuration

在你的可观测性配置中包含 CloudExporter：

🌐 Include CloudExporter in your observability configuration:

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(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(),
        ],
      },
    },
  }),
});

完成配置

🌐 Complete Configuration

new CloudExporter({
  // Optional - defaults to env var
  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,

  // Optional - for self-hosted Mastra Cloud
  endpoint: "https://cloud.your-domain.com",

  // Batching configuration
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before sending batch

  // Diagnostic logging
  logLevel: "info", // debug | info | warn | error
});

查看痕迹

🌐 Viewing Traces

Mastra 云控制台

🌐 Mastra Cloud Dashboard

1. 导航到 cloud.mastra.ai
2. 选择你的项目
3. 转到可观测性 → 跟踪
4. 使用筛选器查找特定痕迹：
   • 服务名称
   • 时间范围
   • 跟踪 ID
   • 错误状态

功能

🌐 Features

• 跟踪时间线 - 可视化执行流程
• 跨度详情 - 输入、输出、元数据
• 性能指标 - 延迟，令牌使用情况
• 团队协作 - 分享追踪链接

性能

🌐 Performance

info

CloudExporter 使用智能批处理来优化网络使用。追踪信息会被缓冲并成批发送，从而在保持几乎实时可见性的同时减少开销。

🌐 CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.

批处理行为

🌐 Batching Behavior

• 追踪记录会被批量处理，批量大小为 maxBatchSize（默认值：1000）
• 批次在满时或经过 maxBatchWaitMs（默认：5 秒）后发送
• 失败的批次将以指数退避方式重试
• 如果 Mastra 云不可访问，则优雅降级

相关

🌐 Related

• 追踪概览
• 默认导出器
• Mastra 云文档