피노로거

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

사용예

src/mastra/index.ts

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

= true

false이면 pino-pretty를 비활성화하고 원시 JSON 행을 기록합니다(로그 수집기에 유용함).

mixin?:

pino.MixinFn

모든 로그 객체에 병합되는 Pino mixin 함수입니다(예: 요청 범위의 traceId 또는 기타 공유 메타데이터).

customLevels?:

Record<string, number>

Pino에 전달되는 사용자 정의 로그 레벨과 숫자 값입니다. 표준 심각도는 계속 debug, info, warn, error를 통해 기록되며, 추가 레벨은 Pino의 사용자 정의 레벨 동작을 따릅니다.

로그 강화mixin

모든 행에 동일한 구조화된 필드를 포함하려면(나머지 서비스와의 상관관계 분석을 위해) mixin을 사용하세요.

src/mastra/index.ts

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 인스턴스로 전달합니다.

src/mastra/logger.ts

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로 변환되어 구성된 파일 경로에 영구 저장됩니다.

src/mastra/loggers/file-transport.ts

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

파일 전송 사용량

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

Upstash 전송(원격 로그 유출)

UpstashTransport를 사용하여 구조화된 로그를 원격 Redis 목록으로 스트리밍합니다. 로거는 문자열 메시지와 구조화된 메타데이터 객체를 받습니다. 분산 환경을 위한 중앙 집중식 로깅을 지원하며 destinationPath, type, runId를 기준으로 필터링할 수 있습니다.

src/mastra/loggers/upstash-transport.ts

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

업스태시 전송 사용량

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

맞춤형 운송

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

센트리 수송 예시

createCustomTransport를 사용하여 사용자 정의 전송을 만들고 pino-sentry-transport와 같은 타사 로깅 스트림과 통합합니다. 이를 통해 고급 모니터링과 Observability를 위해 로그를 Sentry 같은 외부 시스템으로 전달할 수 있습니다.

src/mastra/loggers/sentry-transport.ts

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