Log

Mastra 的 Log 系統會以結構化格式擷取函式執行作業、輸入資料與輸出回應。

部署至 Mastra 平台時，Log 會顯示在儀表板中。在自行代管或自訂環境中，Log 可根據所設定的 transport 傳送至檔案或外部服務。

給 AI Agent： 執行 npx mastra api log list '{"level":"error","page":0,"perPage":50}'，即可直接檢查近期錯誤 Log，無須開啟 Studio 或撰寫暫用 script。此命令需要已執行且設定 Observability Log 的 Mastra Server；你可以使用 npx mastra dev 啟動本機 Server，或透過 --url 傳入可連線 Server 的 base URL。建立其他 filter 前，請先執行 npx mastra api log list --schema。使用 npx skills add mastra-ai/skills --skill mastra 安裝 Mastra Skill，即可取得完整的 API CLI 探索、目標指定、schema、驗證與錯誤處理指引。

使用 PinoLogger 設定 Log

使用 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。

將 Log 寫入 Observability Storage

設定 Observability 後，所有 logger 呼叫都會自動轉送至 Observability Storage。這表示應用程式與 Mastra 內部元件的每次 debug、info、warn、error 和 trackException 呼叫，都會與 Trace 一起儲存。

不需要變更程式碼。Mastra 會包裝已設定的 logger，使其同時寫入原始 logger（console、檔案或自訂 transport）與 Observability 系統。

設定 Observability Log 層級

你可以獨立於 console logger，控制要將哪些 Log 層級寫入 Observability Storage。請將 logging 選項加入 Observability instance 設定：

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

在此範例中，console logger 會輸出從 debug 開始的所有層級，但只有 info 及以上層級會寫入 Observability Storage。這能保持 Storage 整潔，同時在開發期間保留詳細的 console 輸出。

選項	型別	預設值	說明
enabled	boolean	true	設為 false 可停用將所有 Log 轉送至 Observability Storage。
level	LogLevel	'debug'	最低嚴重程度。低於此層級的 Log 會被捨棄。

查詢 Log

你可以透過 Mastra Client SDK 查詢寫入 Observability Storage 的 Log：

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 等持久化 Storage backend 時，Log 會在重新啟動後保留，並可供歷史分析使用。

自訂 Log

Mastra 可透過 mastra.getLogger() 方法存取 logger instance，並可在 Workflow 步驟和 Tool 中使用。此 logger 支援標準嚴重程度層級：debug、info、warn 和 error。

從 Workflow 步驟寫入 Log

在 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();

從 Tool 寫入 Log

同樣地，Tool 可以透過 mastra 參數存取 logger instance。你可以用它記錄 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: '',
    }
  },
})

使用額外資料寫入 Log

Logger 方法接受選用的第二個參數，用於傳入額外資料。請傳入結構化 object，讓 Log 可在 Observability Storage 中進行篩選。

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();