Skip to Content
API 레퍼런스로거

로깅

ASAPJS는 Winston  기반의 로거를 제공합니다. @asapjs/core의 logger export는 @asapjs/common 패키지의 Winston 인스턴스를 감싸는 래퍼입니다. 컬러라이즈된 사람이 읽기 쉬운 형식으로 stdout에 출력합니다.

임포트

import { logger } from '@asapjs/core';

참고: @asapjs/core는 내부적으로 @asapjs/common에서 logger를 재수출합니다 (packages/core/src/index.ts → export { logger } from '@asapjs/common').

Logger 인터페이스

interface Logger {
  info:  (message: string, ...args: any[]) => void;
  error: (message: string | Error, ...args: any[]) => void;
  warn:  (message: string, ...args: any[]) => void;
  debug: (message: string, ...args: any[]) => void;
}

모든 메서드는 첫 번째 인자로 문자열 메시지를, 이후 가변 인자(...args)를 받습니다. 가변 인자는 Winston의 내부 포맷터에 의해 처리됩니다.

로그 메서드

debug

logger.debug(message: string, ...args: any[]): void

가장 낮은 심각도. 상세한 내부 추적에 사용됩니다.

info

logger.info(message: string, ...args: any[]): void

서버 시작 및 모듈 초기화와 같은 일반 정보 메시지입니다.

warn

logger.warn(message: string, ...args: any[]): void

에러는 아니지만 문제나 성능 저하 상태를 나타낼 수 있는 조건입니다.

error

logger.error(message: string | Error, ...args: any[]): void

error는 첫 번째 인자로 문자열 또는 Error 인스턴스를 받을 수 있습니다:

  • 문자열: 메시지를 그대로 로깅합니다.
  • Error 인스턴스: Error.message를 로그 메시지로 사용하고, 원본 Error 객체를 메타데이터에 포함합니다.
// 문자열 메시지
logger.error('사용자를 찾을 수 없습니다');
 
// Error 인스턴스
logger.error(new Error('DB connection failed'));
 
// 메시지 + 추가 데이터
logger.error('쿼리 실패', err);

출력 형식

모든 로그는 컬러라이즈된 사람이 읽기 쉬운 형식으로 콘솔에 출력됩니다:

2026-02-21 09:15:00 - info: [asapjs] 서버가 시작되었습니다
2026-02-21 09:15:03 - error: [asapjs] 데이터베이스 연결 실패

형식: ${timestamp} - ${level}: [asapjs] ${message}

  • 타임스탬프: YYYY-MM-DD HH:mm:ss
  • [asapjs] 레이블이 모든 로그에 포함
  • 레벨별 색상 적용 (Winston format.colorize())

로그 레벨 설정

현재 공개 로거의 transport 레벨은 debug로 하드코딩되어 있습니다. 네 가지 레벨의 로그가 모두 출력됩니다.

심각도 순서(낮음에서 높음): debug, info, warn, error.

참고: packages/core/src/util/logger.ts에 ASAPJS_LOG_LEVEL 환경 변수로 레벨을 제어하는 구조화된 로거가 구현되어 있으나, 현재 @asapjs/core의 공개 API에 포함되지 않습니다. import { logger } from '@asapjs/core'는 @asapjs/common의 로거를 반환하며, 이 로거에는 ASAPJS_LOG_LEVEL이 적용되지 않습니다.

구조화된 로거 (미노출)

packages/core/src/util/logger.ts에는 프로덕션 환경에 적합한 구조화된 로거가 구현되어 있습니다. 이 로거는 현재 @asapjs/core의 공개 export에 포함되지 않습니다.

LoggerFacade 인터페이스

type LogFn = (message: string, meta?: LogMeta) => void;
 
interface LoggerFacade {
  debug: LogFn;
  info:  LogFn;
  warn:  LogFn;
  error: {
    (message: string, meta?: LogMeta): void;
    (message: string, err: unknown, meta?: LogMeta): void;
  };
}

LogMeta 인터페이스

export interface LogMeta {
  operation?: string;                    // 호출 위치 (ClassName.methodName)
  executeId?: string;                    // 요청/흐름 식별자
  err?: unknown;                         // Error 객체
  context?: Record<string, unknown>;     // 도메인 데이터
  [key: string]: unknown;               // 추가 필드
}

주요 차이점

항목공개 로거 (@asapjs/common)미노출 로거 (core/util/logger.ts)
importimport { logger } from '@asapjs/core'공개 API 없음
출력 형식컬러라이즈 텍스트JSON
시그니처(message, ...args)(message, meta?: LogMeta)
레벨 제어하드코딩 debugASAPJS_LOG_LEVEL 환경 변수 (기본: info)
meta 검증없음비객체 전달 시 warn + 호출 무시
Error 정규화Error.message 추출{ name, message, stack } 자동 정규화

사용 예제

표준 info 로그

import { logger } from '@asapjs/core';
 
logger.info('User registered successfully');

Error 인스턴스를 포함한 error

try {
  const user = await UsersTable.findByPk(id);
} catch (err) {
  logger.error('Database query failed', err);
  throw err;
}

Debug 추적

logger.debug('Executing password hash');

관련 항목

Last updated on
부트스트랩Swagger