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

# 피노로거

Logger 인스턴스는 다음을 사용하여 생성됩니다.`new PinoLogger()`심각도 수준에서 이벤트를 기록하는 방법을 제공합니다.

## 사용예

```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`): 이 로거의 로그를 그룹화하고 식별하는 데 사용하는 레이블입니다.

**level** (`"debug" | "info" | "warn" | "error"`): 최소 로그 레벨을 설정합니다. 이 레벨보다 낮은 메시지는 무시됩니다.

**transports** (`Record<string, LoggerTransport>`): 로그를 영구 저장하는 데 사용되는 전송 인스턴스의 맵입니다.

**overrideDefaultTransports** (`boolean`): true이면 기본 콘솔 전송을 비활성화합니다.

**formatters** (`pino.LoggerOptions['formatters']`): 로그 직렬화를 위한 사용자 정의 Pino 포매터입니다.

**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`피노에게 전달됩니다.`PinoLogger` only exposes `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` 행이 모두 출력됩니다.

## 파일 전송(구조화된 로그)

`FileTransport`를 사용하여 구조화된 로그를 파일에 기록합니다. 로거는 첫 번째 인수로 일반 메시지를, 두 번째 인수로 구조화된 메타데이터를 받습니다. 이들은 내부적으로 `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',
})
```

### 파일 전송 사용량

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

## Upstash 전송(원격 로그 유출)

`UpstashTransport`를 사용하여 구조화된 로그를 원격 Redis 목록으로 스트리밍합니다. 로거는 문자열 메시지와 구조화된 메타데이터 객체를 받습니다. 분산 환경을 위한 중앙 집중식 로깅을 지원하며 `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',
})
```

### 업스태시 전송 사용량

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

## 맞춤형 운송

`createCustomTransport` 유틸리티를 사용하여 모든 로깅 서비스 또는 스트림과 통합할 수 있는 사용자 정의 전송을 만들 수 있습니다.

### 센트리 수송 예시

`createCustomTransport`를 사용하여 사용자 정의 전송을 만들고 `pino-sentry-transport`와 같은 타사 로깅 스트림과 통합합니다. 이를 통해 고급 모니터링과 Observability를 위해 로그를 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 },
})
```