로깅

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

기본 사용법

import { logger } from '@asapjs/core';
 
// 기본 정보 로그
logger.info('서버가 시작되었습니다');
 
// 추가 인자와 함께
logger.info('사용자 등록 완료', { userId: 42, email: 'alice@example.com' });

logger API

import { logger } from '@asapjs/core'로 사용하는 로거는 @asapjs/common 패키지에서 제공됩니다. 네 가지 메서드를 지원합니다:

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의 splat 포맷터에 의해 처리됩니다.

출력 형식

현재 공개 API의 로거는 컬러라이즈된 사람이 읽을 수 있는 형식으로 출력합니다:

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

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

• 타임스탬프 형식: YYYY-MM-DD HH:mm:ss
• [asapjs] 레이블이 모든 로그에 포함됩니다
• 콘솔 출력에 레벨별 색상이 적용됩니다

로그 레벨

현재 공개 로거의 레벨은 debug로 설정되어 있어 네 가지 레벨의 로그가 모두 출력됩니다.

참고: packages/core/src/util/logger.ts에 ASAPJS_LOG_LEVEL 환경 변수로 레벨을 제어하고 JSON 형식으로 출력하는 구조화된 로거(LoggerFacade)가 구현되어 있으나, 현재 @asapjs/core의 공개 API로 노출되지 않습니다. import { logger } from '@asapjs/core'는 @asapjs/common의 컬러 로거를 반환합니다.

error 메서드

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

// 문자열 메시지
logger.error('사용자를 찾을 수 없습니다');
 
// Error 인스턴스 직접 전달
try {
  await UsersTable.findByPk(id);
} catch (err) {
  logger.error(err);  // Error.message가 로그됨, 추가 메타에 error 객체 포함
}
 
// 메시지 + 추가 인자
logger.error('데이터베이스 쿼리 실패', err);

Error 인스턴스가 첫 번째 인자로 전달되면 error.message가 메시지로 사용되고, 원본 Error 객체가 메타데이터에 포함됩니다.

사용 예시

Application 계층에서 로깅

import { logger } from '@asapjs/core';
import UsersTable from '../domain/entity/UsersTable';
 
export default class UserApplication {
  async register(dto: CreateUserDto) {
    const existingUser = await UsersTable.findOne({
      where: { email: dto.email },
    });
 
    if (existingUser) {
      logger.warn('중복 가입 시도');
      throw new Error('Email already exists');
    }
 
    const user = await UsersTable.create({ ... } as any);
 
    logger.info('사용자 등록 완료');
 
    return user;
  }
}

에러 핸들링과 함께 사용

try {
  const result = await someOperation();
} catch (err) {
  logger.error('작업 실패', err);
  throw err;
}

프레임워크 내부 로깅

ASAPJS 프레임워크 모듈들은 내부적으로 동일한 logger를 사용합니다. 주요 내부 로그 메시지:

구조화된 로거 (미노출)

packages/core/src/util/logger.ts에는 아래 기능을 갖춘 구조화된 로거가 구현되어 있으나, 현재 @asapjs/core의 공개 export에 포함되지 않습니다:

• JSON 출력: 모든 환경에서 일관된 JSON 형식
• ASAPJS_LOG_LEVEL 환경 변수: 로그 레벨 제어 (기본값: info)
• LogMeta 인터페이스: operation, executeId, err, context 필드로 구조화된 메타데이터
• LoggerFacade: (message: string, meta?: LogMeta) 시그니처
• meta 검증: 비객체 값 전달 시 warn 진단 + 원래 호출 무시

이 로거를 사용하려면 현재는 직접 import해야 합니다:

// 직접 import (공개 API가 아님 — 향후 변경될 수 있음)
import logger from '@asapjs/core/util/logger';

향후 개선: 구조화된 로거가 @asapjs/core의 공개 API로 노출되면 이 문서가 업데이트될 예정입니다.

관련 문서

• Logging API 레퍼런스 — Logger 상세 API
• Bootstrap — Application 클래스와 글로벌 초기화
• Database — Sequelize 모듈 시작 로그