> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 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 專案](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)時，系統預設會包含 `PinoLogger`。

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

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

如需所有可用的設定選項，請參閱 [`PinoLogger`](https://mastra.zisheng.pro/zh-TW/reference/logging/pino-logger)。

## 將 Log 寫入 Observability Storage

設定 [Observability](https://mastra.zisheng.pro/zh-TW/docs/observability/overview) 後，所有 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 設定：

```typescript
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：

```typescript
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。你可以記錄與步驟執行作業相關的訊息。

```typescript
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 執行期間的特定活動。

```typescript
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 中進行篩選。

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