Skip to main content

可观测性概览

🌐 Observability Overview

Mastra 为 AI 应用提供可观测性功能。监控大型语言模型（LLM）操作，追踪代理决策，并使用能够理解 AI 特定模式的工具调试复杂工作流。

🌐 Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.

主要特点
Direct link to 主要特点

🌐 Key Features

追踪
Direct link to 追踪

🌐 Tracing

针对 AI 操作的专门跟踪，包括捕获：

🌐 Specialized tracing for AI operations that captures:

  • 模型交互：令牌使用量、延迟、提示词和输出
  • 代理执行：决策路径、工具调用和内存操作
  • 工作流程步骤：分支逻辑、并行执行和步骤输出
  • 自动化检测：使用装饰器进行追踪

存储要求
Direct link to 存储要求

🌐 Storage Requirements

DefaultExporter 会将痕迹持久化到你配置的存储后端。并非所有存储提供商都支持可观测性——完整列表请参见 Storage Provider Support。

🌐 The DefaultExporter persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see Storage Provider Support.

对于高流量的生产环境，我们建议通过 复合存储 使用 ClickHouse 来处理可观察性字段。详细信息请参阅 生产推荐。

🌐 For production environments with high traffic, we recommend using ClickHouse for the observability domain via composite storage. See Production Recommendations for details.

快速开始
Direct link to 快速开始

🌐 Quick Start

在你的 Mastra 实例中配置可观察性：

🌐 Configure Observability in your Mastra instance:

src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { PinoLogger } from "@mastra/loggers";
import { LibSQLStore } from "@mastra/libsql";
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from "@mastra/observability";

export const mastra = new Mastra({
  logger: new PinoLogger(),
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: "file:./mastra.db", // Storage is required for tracing
  }),
  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
        ],
      },
    },
  }),
});
Serverless environments

The file:./mastra.db storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the Vercel deployment guide for a complete example.

使用这个基本设置，你将在 Studio 和 Mastra Cloud 中看到跟踪和日志。

🌐 With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.

我们还支持各种外部跟踪提供商，例如 MLflow、Langfuse、Braintrust 以及任何兼容 OpenTelemetry 的平台（Datadog、New Relic、SigNoz 等）。有关详细信息，请参阅 Tracing 文档。

🌐 We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the Tracing documentation.

接下来是什么？
Direct link to 接下来是什么？

🌐 What's Next?

目录