Logging

Mastra 的日志系统以结构化格式捕获函数执行、输入数据和输出响应。

部署到 Mastra platform 时，日志会显示在仪表盘中。在自托管或自定义环境中，日志可以根据配置的 transports 定向到文件或外部服务。

For AI agents: Run npx mastra api log list '{"level":"error","page":0,"perPage":50}' to inspect recent error logs directly instead of opening Studio or writing a temporary script. The command requires a running Mastra server with observability logging configured; start the local server with npx mastra dev, or pass the reachable server's base URL with --url. Run npx mastra api log list --schema before constructing different filters. Install Mastra's skill with npx skills add mastra-ai/skills --skill mastra for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.

使用 PinoLogger 配置日志

使用 CLI 初始化新的 Mastra 项目时，默认包含 PinoLogger。

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})

访问 PinoLogger查看所有可用配置选项。

记录日志到可观测性存储

配置可观测性后，默认情况下所有 logger 调用都会自动转发到你的可观测性存储。来自应用和 Mastra 内部组件的每一次 debug、info、warn、error 和 trackException 调用都会与 traces 一起存储。

无需更改代码。支持适配器的 loggers（PinoLogger 和 ConsoleLogger）会将每条记录写入自己的目的地，并从同一条记录派生出导出的日志。不支持适配器的自定义 loggers 会被包装，以便同时写入原始 logger 和可观测性系统。

Trace 关联的日志输出

当日志调用发生在被追踪的操作中（agent 运行、workflow 步骤或 tool 调用）时，Mastra 会将 trace_id 和 span_id 注入 logger 的原生输出。这些字段使用 W3C trace context 格式，并与 Studio 中显示的 trace 匹配，因此你可以直接将 stdout 日志行与其 trace 关联起来。

要在 stdout 上获得可机器解析的 JSON，请将 PinoLogger 配置为 prettyPrint: false；pretty printing 默认启用，会生成人类可读的文本而不是 JSON：

src/mastra/index.ts

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'info', prettyPrint: false }),
})

此时记录看起来像这样：

{
  "level": 30,
  "time": 1755522000000,
  "name": "Mastra",
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "span_id": "b7ad6b7169203331",
  "msg": "tool executed"
}

在被追踪的操作之外，这些字段会被省略。ConsoleLogger 则会将相同的字段作为对象参数追加到其控制台输出中。使用 PinoLogger 时，这些字段会到达每个目的地：stdout、文件和自定义 transports。如果你提供自己的 pino mixin，其字段会被保留，但在冲突时 trace_id 和 span_id 优先。

关联和导出可以通过 loggerOptions 配置独立控制：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
  loggerOptions: {
    correlation: true, // inject trace_id/span_id into native log output (default: true)
    export: false, // keep trace-correlated output without storing logs in observability (default: true)
  },
})

自定义 loggers

自定义 IMastraLogger 实现继续有效：Mastra 使用已弃用的双写回退方案，将日志调用转发到可观测性，而不会向 logger 的原生输出添加 trace_id 或 span_id。要获得 trace 关联的输出，请实现 @mastra/core/logger 中的 __attachObservability() 适配器 hook：

import { MastraLogger, buildLogRecordData } from '@mastra/core/logger'
import type { LoggerAdapterContext } from '@mastra/core/logger'

class MyLogger extends MastraLogger {
  #adapterContext?: LoggerAdapterContext

  __attachObservability(ctx: LoggerAdapterContext): void {
    this.#adapterContext = ctx
  }

  #log(level: 'debug' | 'info' | 'warn' | 'error', message: string, args: unknown[]): void {
    const ctx = this.#adapterContext
    // Inject trace fields into your native record when correlation is enabled
    const traceFields = ctx?.options.correlation ? ctx.resolveTraceFields() : undefined
    console[level === 'debug' ? 'info' : level](
      message,
      ...args,
      ...(traceFields ? [traceFields] : []),
    )
    // Export the same record to observability when export is enabled
    if (ctx?.options.export) {
      ctx.getLogSink()?.[level](message, buildLogRecordData(args))
    }
  }

  debug(message: string, ...args: unknown[]): void {
    this.#log('debug', message, args)
  }

  info(message: string, ...args: unknown[]): void {
    this.#log('info', message, args)
  }

  warn(message: string, ...args: unknown[]): void {
    this.#log('warn', message, args)
  }

  error(message: string, ...args: unknown[]): void {
    this.#log('error', message, args)
  }
}

配置可观测性日志级别

你可以独立于控制台 logger 控制哪些日志级别进入可观测性存储。在可观测性实例配置中添加 logging 选项：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
        logging: {
          enabled: true, // set to false to disable log forwarding
          level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
        },
      },
    },
  }),
})

在此示例中，控制台 logger 输出从 debug 开始的所有级别，但只有 info 及以上级别会写入可观测性存储。这样既保持存储干净，又能在开发期间获得详细的控制台输出。

选项	类型	默认值	描述
enabled	boolean	true	设置为 false 可禁用所有日志转发到可观测性存储。
level	LogLevel	'debug'	最低严重级别。低于此级别的日志会被丢弃。

查询日志

写入可观测性存储的日志可以通过 Mastra 客户端 SDK 查询：

import { MastraClient } from '@mastra/client-js'

const client = new MastraClient()

const logs = await client.listLogsVNext({
  filters: { level: 'error' },
  pagination: { page: 1, perPage: 50 },
  orderBy: { field: 'timestamp', direction: 'desc' },
})

使用 DuckDB 或 ClickHouse 等持久化存储后端时，日志在重启后仍然存在，并可用于历史分析。

自定义日志

Mastra 通过 mastra.getLogger() 方法提供对 logger 实例的访问，该方法在 workflow 步骤和 tools 中均可用。Logger 支持标准严重级别：debug、info、warn 和 error。

从 workflow 步骤记录日志

在 workflow 步骤中，通过 execute 函数内的 mastra 参数访问 logger。你可以记录与该步骤执行相关的消息。

src/mastra/workflows/test-workflow.ts

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const logger = mastra.getLogger();
    logger.info("workflow info log");

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

从 tools 记录日志

类似地，tools 可以通过 mastra 参数访问 logger 实例。使用它来记录执行期间 tool 特定的活动。

src/mastra/tools/test-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const testTool = createTool({
  execute: async (inputData, context) => {
    const logger = context?.mastra.getLogger()
    logger?.info('tool info log')

    return {
      output: '',
    }
  },
})

记录带附加数据的日志

Logger 方法接受可选的第二个参数用于附加数据。传入结构化对象，使日志在可观测性存储中可被过滤。

src/mastra/workflows/test-workflow.ts

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({
  execute: async ({ mastra }) => {
    const testAgent = mastra.getAgent("testAgent");
    const logger = mastra.getLogger();
    
    logger.info("workflow info log", { agent: testAgent });

    return {
      output: ""
    };
  }
});

export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();