Skip to Content
문서가이드로깅

로깅

ASAPJS는 Winston  기반의 로거를 제공합니다. @asapjs/core에서 export되는 logger는 @asapjs/common 패키지의 Winston 인스턴스를 감싼 래퍼이며, **설정(config 또는 env)**에 따라 사람이 읽기 쉬운 형식(pretty) 또는 JSON 한 줄 형식으로 stdout에 출력합니다.

기본 사용법

import { logger } from '@asapjs/core';
 
// 기본 정보 로그
logger.info('서버가 시작되었습니다');
 
// 메타 객체와 함께 (operation, executeId, context 등)
logger.info('사용자 등록 완료', { operation: 'UserApplication.register', context: { userId: 42 } });

logger API

import { logger } from '@asapjs/core'로 사용하는 로거는 @asapjs/common에서 제공됩니다. 메시지 + 선택적 메타 객체(LogMeta) 시그니처를 사용합니다.

interface LogMeta {
  operation?: string;   // 함수/유스케이스명
  executeId?: string;   // 실행/흐름 식별자
  err?: unknown;        // error 레벨에서 사용 (stack 포함)
  context?: Record<string, unknown>;
  [key: string]: unknown;
}
 
interface Logger {
  info:  (message: string, meta?: LogMeta) => void;
  warn:  (message: string, meta?: LogMeta) => void;
  debug: (message: string, meta?: LogMeta) => void;
  error: (message: string, meta?: LogMeta) => void;
  error: (message: string, err: unknown, meta?: LogMeta) => void;
}
메서드시그니처설명
info(message: string, meta?: LogMeta)서버 시작, 모듈 초기화 등 일반 정보
warn(message: string, meta?: LogMeta)주의가 필요한 상태
debug(message: string, meta?: LogMeta)상세 내부 추적
error(message: string, meta?: LogMeta)오류 상황
error(message: string, err: unknown, meta?: LogMeta)오류 + Error 객체(스택 등 읽기 쉬운 형식으로 출력)

참고: 메타는 객체만 허용됩니다. 비객체를 넘기면 로거가 경고를 남기고 해당 호출은 무시됩니다.

로그 설정 (config / env)

로그 레벨과 출력 형식은 AsapJSConfig.log 또는 환경 변수로 제어합니다. 설정은 config.ts(또는 앱 설정 객체)에서 한 곳으로 관리하고, 프로덕션에서는 env로 값을 넘기면 됩니다.

항목config환경 변수기본값
레벨config.log.levelASAPJS_LOG_LEVEL'info'
형식config.log.formatASAPJS_LOG_FORMAT개발: 'pretty', 프로덕션: 'json'
  • 형식
    • pretty: 타임스탬프 + 레벨(색상) + 메시지. 에러는 이름: 메시지 + 스택 일부로 읽기 쉽게 출력.
    • json: 한 줄 JSON. 로그 수집/검색용으로 프로덕션에서 권장.
  • 우선순위: config.log가 있으면 그 값을 쓰고, 없으면 env, 그다음 환경에 따른 기본값(개발이면 pretty, 프로덕션면 json)입니다.
  • Application 생성자에서 setConfig() 직후 configureLogger()가 자동 호출되어, 이 시점의 config.log(및 env)가 로거에 반영됩니다.

설정 예시 (config에서 관리)

// src/config.ts
export default {
  port: 3000,
  dirname: __dirname,
  extensions: ['@asapjs/router', '@asapjs/sequelize'],
  // 프로덕션에서 env(ASAPJS_LOG_LEVEL, ASAPJS_LOG_FORMAT)로 인입
  log:
    process.env.ASAPJS_LOG_FORMAT || process.env.ASAPJS_LOG_LEVEL
      ? {
          format: process.env.ASAPJS_LOG_FORMAT as 'pretty' | 'json' | undefined,
          level: process.env.ASAPJS_LOG_LEVEL,
        }
      : undefined,
};

출력 형식

  • pretty (기본·개발): ${timestamp} ${level}: ${message} + 메타가 있으면 이어서, 에러가 있으면 이름: 메시지와 스택 일부를 다음 줄에 출력. 레벨에만 색상 적용.
  • json (프로덕션 권장): 한 줄 JSON. 타임스탬프, level, message, 기타 메타 포함.

pretty 예시:

2026-02-27 14:26:45 warn: @router SWAGGER useAuth is disabled! Please add config.swagger.useAuth & config.swagger.userObject
2026-02-27 14:26:45 info: @asapjs :: Server is listening at 3000
2026-02-27 14:26:45 error: @sequelize :: Unable to connect to the database:
  SequelizeConnectionRefusedError: connect ECONNREFUSED 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:...)
  • 타임스탬프: YYYY-MM-DD HH:mm:ss
  • 에러 객체는 JSON 덤프가 아니라 읽기 쉬운 형태로 포맷됩니다.

로그 레벨

레벨심각도 (낮→높)용도
debug최저상세 내부 추적
info보통서버 시작, 모듈 초기화
warn높음주의가 필요한 상태
error최고오류 상황

레벨은 config.log.level 또는 ASAPJS_LOG_LEVEL로 지정하며, 지정하지 않으면 기본값은 info입니다.

error 메서드

logger.error는 다음 두 패턴을 지원합니다:

// 메시지만
logger.error('사용자를 찾을 수 없습니다');
 
// 메시지 + 메타
logger.error('작업 실패', { operation: 'UserApplication.get', executeId: req.id });
 
// 메시지 + Error 객체 (두 번째 인자). pretty 형식에서는 이름/메시지/스택이 읽기 쉽게 출력됨
try {
  await UsersTable.findByPk(id);
} catch (err) {
  logger.error('데이터베이스 쿼리 실패', err);
}
 
// 메시지 + Error + 메타
logger.error('쿼리 실패', err, { operation: 'findByPk', context: { id } });

Error를 두 번째 인자로 넘기면 로거가 name, message, stack을 정규화해, pretty 모드에서는 JSON 덤프가 아니라 한두 줄 요약 + 스택 일부로 출력합니다.

사용 예시

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를 사용합니다. 주요 내부 로그 메시지:

모듈메시지레벨
@asapjs/sequelize@sequelize :: Database connected.info
@asapjs/sequelize@sequelize :: database initalize.info
@asapjs/sequelize@sequelize :: add models to sequelize instance.info
@asapjs/sequelize@sequelize :: models sync finishedinfo
@asapjs/core@asapjs :: Server is listening at {port}info
@asapjs/socket@socket :: PUB Client Error. error
@asapjs/socket@socket :: SUB Client Error. error
@asapjs/socket@socket :: Redis connect error.error

관련 문서

  • @asapjs/core — logger, configureLogger, AsapJSConfig.log 레퍼런스
  • 배포 — 프로덕션 환경 변수 (ASAPJS_LOG_LEVEL, ASAPJS_LOG_FORMAT)
Last updated on
에러 처리페이지네이션