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

# PinoLogger

使用 `new PinoLogger()` 建立 Logger 實例後，便可透過其方法記錄不同嚴重程度的事件。

## 使用範例

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

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

## 參數

**name** (`string`): 用於分組及識別此 Logger 所產生日誌的標籤。

**level** (`"debug" | "info" | "warn" | "error"`): 設定最低日誌級別。低於此級別的訊息會被忽略。

**transports** (`Record<string, LoggerTransport>`): 用於持久儲存日誌的 transport 實例對照表。

**overrideDefaultTransports** (`boolean`): 設為 true 時，停用預設的 console transport。

**formatters** (`pino.LoggerOptions['formatters']`): 用於序列化日誌的自訂 Pino formatter。

**redact** (`pino.LoggerOptions['redact']`): 從日誌輸出遮蔽敏感欄位的路徑或選項（Pino redact）。

**prettyPrint** (`boolean`): 設為 false 時，停用 pino-pretty 並寫入原始 JSON 行（適用於日誌彙集器）。 (Default: `true`)

**mixin** (`pino.MixinFn`): 會合併至每個日誌物件的 Pino mixin 函數（例如請求範圍內的 traceId 或其他共用元數據）。

**customLevels** (`Record<string, number>`): 傳遞至 Pino 的自訂日誌級別及數值。標準嚴重程度仍會透過 debug、info、warn 及 error 記錄；額外級別則遵循 Pino 的自訂級別行為。

## 使用 `mixin` 豐富日誌資料

如果想在每一行加入相同的結構化欄位（以便與其他服務互相對照），可使用 `mixin`：

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

function getTraceContext() {
  return { traceId: 'abc-123' }
}

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

## 自訂級別

`customLevels` 會直接傳遞至 Pino。`PinoLogger` 只公開 `debug`、`info`、`warn` 及 `error`；如要使用任何額外的級別名稱（例如 `audit`），請建立子類別，並將其轉送至底層 Pino 實例：

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

type AuditLevel = 'audit'

class MastraPinoWithAudit extends PinoLogger<AuditLevel> {
  audit(message: string, meta: Record<string, unknown> = {}) {
    this.logger.audit(meta, message)
  }
}

const logger = new MastraPinoWithAudit({
  name: 'Mastra',
  level: 'info',
  customLevels: { audit: 35 },
})

export const mastra = new Mastra({ logger })
```

數值遵循 Pino 的排序方式（內置級別使用 10 至 60）。級別 `35` 位於 `info`（30）與 `warn`（40）之間，因此當 `level: 'info'` 時，`info` 及 `audit` 行都會輸出。

## 檔案 transport（結構化日誌）

使用 `FileTransport` 將結構化日誌寫入檔案。Logger 接受純文字訊息作為第一個引數，並接受結構化元數據作為第二個引數。兩者會在內部轉換為 `BaseLogMessage`，並持久儲存至已設定的檔案路徑。

```typescript
import { FileTransport } from '@mastra/loggers/file'
import { PinoLogger } from '@mastra/loggers/pino'

export const fileLogger = new PinoLogger({
  name: 'Mastra',
  transports: { file: new FileTransport({ path: 'test-dir/test.log' }) },
  level: 'warn',
})
```

### 檔案 transport 用法

```typescript
fileLogger.warn('Low disk space', {
  destinationPath: 'system',
  type: 'WORKFLOW',
})
```

## Upstash transport（遠端日誌接收端）

使用 `UpstashTransport` 將結構化日誌串流至遠端 Redis list。Logger 接受字串訊息及結構化元數據物件。它支援分散式環境的集中式日誌記錄，並可按 `destinationPath`、`type` 及 `runId` 篩選。

```typescript
import { UpstashTransport } from '@mastra/loggers/upstash'
import { PinoLogger } from '@mastra/loggers/pino'

export const upstashLogger = new PinoLogger({
  name: 'Mastra',
  transports: {
    upstash: new UpstashTransport({
      listName: 'production-logs',
      upstashUrl: process.env.UPSTASH_URL!,
      upstashToken: process.env.UPSTASH_TOKEN!,
    }),
  },
  level: 'info',
})
```

### Upstash transport 用法

```typescript
upstashLogger.info('User signed in', {
  destinationPath: 'auth',
  type: 'AGENT',
  runId: 'run_123',
})
```

## 自訂 transport

你可以使用 `createCustomTransport` 工具函數建立自訂 transport，以整合任何日誌服務或串流。

### Sentry transport 範例

使用 `createCustomTransport` 建立自訂 transport，並將其與 `pino-sentry-transport` 等第三方日誌串流整合。這樣便可將日誌轉送至 Sentry 等外部系統，以進行進階監察及可觀測性分析。

```typescript
import { createCustomTransport } from '@mastra/core/loggers'
import { PinoLogger } from '@mastra/loggers/pino'
import pinoSentry from 'pino-sentry-transport'

const sentryStream = await pinoSentry({
  sentry: {
    dsn: 'YOUR_SENTRY_DSN',
    _experiments: {
      enableLogs: true,
    },
  },
})

const customTransport = createCustomTransport(sentryStream)

export const sentryLogger = new PinoLogger({
  name: 'Mastra',
  level: 'info',
  transports: { sentry: customTransport },
})
```