Naite 사용하기

Naite를 활용한 효과적인 디버깅 방법을 다룹니다.

Naite란?

Naite는 Sonamu의 테스트 전용 로깅 시스템으로, 테스트 실행 중 발생하는 모든 로그를 수집하고 분석할 수 있습니다. 주요 특징:

테스트별로 로그 격리
키-값 기반 로그 저장
강력한 쿼리 기능
Naite Viewer로 시각화

기본 사용법

1. 로그 기록하기

import { Naite } from "sonamu";

describe("User API", () => {
  test("사용자 생성", async () => {
    const email = "[email protected]";
    
    // 로그 기록
    Naite.t("user.create.input", { email });
    
    const user = await UserModel.create({ email });
    
    Naite.t("user.create.output", { userId: user.id });
    
    expect(user.email).toBe(email);
  });
});

2. 로그 조회하기

테스트 실패 시 로그를 확인하여 문제를 파악할 수 있습니다:

test("디버깅 예제", async () => {
  try {
    const result = await complexOperation();
    expect(result).toBe(expectedValue);
  } catch (error) {
    // 실패 시 로그 확인
    const logs = Naite.getAll();
    console.log("테스트 로그:", logs);
    throw error;
  }
});

디버깅 패턴

API 요청/응답 추적

test("API 호출 추적", async () => {
  const params = { page: 1, limit: 10 };
  
  // 요청 기록
  Naite.t("api.request", { 
    method: "findMany", 
    params 
  });
  
  const users = await UserModel.findMany(params);
  
  // 응답 기록
  Naite.t("api.response", { 
    count: users.length,
    firstUser: users[0]
  });
  
  expect(users.length).toBeGreaterThan(0);
});

데이터베이스 쿼리 추적

test("쿼리 추적", async () => {
  const userId = 1;
  
  // 쿼리 전
  Naite.t("db.query.before", { userId });
  
  const user = await UserModel.findById(userId);
  
  // 쿼리 후
  Naite.t("db.query.after", { 
    found: !!user,
    data: user 
  });
  
  expect(user).toBeDefined();
});

비즈니스 로직 흐름 추적

test("주문 프로세스 추적", async () => {
  const orderId = 1;
  
  Naite.t("order.process.start", { orderId });
  
  // 1. 주문 조회
  const order = await OrderModel.findById(orderId);
  Naite.t("order.found", { status: order.status });
  
  // 2. 결제 처리
  const payment = await processPayment(order);
  Naite.t("payment.processed", { 
    paymentId: payment.id,
    amount: payment.amount 
  });
  
  // 3. 주문 상태 업데이트
  await OrderModel.updateStatus(orderId, "paid");
  Naite.t("order.status.updated", { newStatus: "paid" });
  
  Naite.t("order.process.complete", { orderId });
});

로그 키 네이밍 규칙

계층적 구조로 키를 설계하면 나중에 쿼리하기 쉽습니다:

// ✅ 좋은 키 네이밍
Naite.t("user.create.input", data);
Naite.t("user.create.validation", result);
Naite.t("user.create.output", user);

// ✅ 도메인별 분리
Naite.t("order.payment.start", params);
Naite.t("order.payment.complete", result);

// ❌ 나쁜 키 네이밍
Naite.t("data1", data);
Naite.t("result", result);
Naite.t("test", value);

권장 패턴:

{domain}.{action}.{stage}
예: user.create.input, order.payment.complete

조건부 로깅

디버깅이 필요한 경우에만 로그를 활성화:

const DEBUG = process.env.DEBUG === "true";

test("조건부 로깅", async () => {
  if (DEBUG) {
    Naite.t("debug.start", { timestamp: Date.now() });
  }
  
  const result = await someOperation();
  
  if (DEBUG) {
    Naite.t("debug.result", result);
  }
  
  expect(result).toBeDefined();
});

Model에서 Naite 사용

비즈니스 로직에서 Naite로 로그를 남길 수 있습니다:

class UserModelClass extends BaseModel {
  @api()
  async createUser(name: string, email: string) {
    // Naite.t()로 로그 기록
    Naite.t("user.input", { name, email });
    
    const user = await this.save({ name, email });
    
    Naite.t("user.created", user);
    
    return user;
  }
}

테스트에서 확인:

test("Naite 로그 확인", async () => {
  await UserModel.createUser("Alice", "[email protected]");
  
  // .first()로 첫 번째 데이터 추출
  const input = Naite.get("user.input").first();
  const created = Naite.get("user.created").first();
  
  expect(input.name).toBe("Alice");
  expect(created.id).toBeDefined();
});

로그 쿼리

Naite는 강력한 쿼리 기능을 제공합니다:

test("로그 쿼리", async () => {
  // 여러 작업 수행
  await createUsers();
  await processOrders();
  
  // 특정 키로 조회
  const userLogs = Naite.get("user").result();
  
  // 패턴으로 조회 (wildcard 지원)
  const createLogs = Naite.get("*.create.*").result();
  
  // 전체 로그
  const allLogs = Naite.getAll();
  
  console.log("User logs:", userLogs);
  console.log("Create logs:", createLogs);
  console.log("All logs:", allLogs);
});

NaiteQuery 메서드

Naite.get()은 NaiteQuery 객체를 반환합니다:

test("NaiteQuery 메서드", async () => {
  Naite.t("test.data", { value: 1 });
  Naite.t("test.data", { value: 2 });
  Naite.t("test.data", { value: 3 });
  
  // 첫 번째 데이터
  const first = Naite.get("test.data").first();
  console.log(first); // { value: 1 }
  
  // 마지막 데이터
  const last = Naite.get("test.data").last();
  console.log(last); // { value: 3 }
  
  // 모든 데이터 배열
  const all = Naite.get("test.data").result();
  console.log(all); // [{ value: 1 }, { value: 2 }, { value: 3 }]
});

Naite Viewer 사용

테스트 실행 후 Naite Viewer로 로그를 시각화합니다:

# 테스트 실행
pnpm test

# Naite Viewer 실행
pnpm naite:view

Viewer 기능:

테스트별 로그 필터링
키 기반 검색
타임라인 뷰
로그 내보내기

디버깅 워크플로우

1. 테스트 실패 시

test("실패하는 테스트", async () => {
  // 충분한 로그 추가
  Naite.t("test.start", { timestamp: Date.now() });
  
  try {
    const result = await problematicFunction();
    Naite.t("test.result", result);
    expect(result).toBe(expectedValue);
  } catch (error) {
    // 에러 발생 시 전체 로그 출력
    console.log("=== Naite Logs ===");
    console.log(JSON.stringify(Naite.getAll(), null, 2));
    throw error;
  }
});

2. 로그 분석

afterEach(() => {
  // 테스트 후 로그 요약
  const allLogs = Naite.getAll();
  const errorKeys = Object.keys(allLogs).filter(key => 
    key.includes("error") || key.includes("fail")
  );
  
  if (errorKeys.length > 0) {
    const errorLogs = errorKeys.map(key => ({ key, data: allLogs[key] }));
    console.log("⚠️ 에러 로그:", errorLogs);
  }
});

3. 특정 시나리오 재현

test("버그 재현", async () => {
  // 버그가 발생한 시나리오 재현
  Naite.t("bug.reproduction.start", {
    scenario: "사용자 생성 후 즉시 삭제"
  });
  
  const user = await UserModel.create({ email: "[email protected]" });
  Naite.t("bug.user.created", user);
  
  await UserModel.del(user.id);
  Naite.t("bug.user.deleted", { userId: user.id });
  
  // 다시 조회 시도
  const deletedUser = await UserModel.findById(user.id);
  Naite.t("bug.user.found", { found: !!deletedUser });
  
  expect(deletedUser).toBeNull();
});

성능 디버깅

로그에 타임스탬프를 추가하여 성능 분석:

test("성능 측정", async () => {
  const start = Date.now();
  Naite.t("perf.start", { timestamp: start });
  
  // 무거운 작업
  const result = await heavyOperation();
  
  const end = Date.now();
  Naite.t("perf.end", { 
    timestamp: end,
    duration: end - start,
    result 
  });
  
  // 성능 기준 검증
  expect(end - start).toBeLessThan(1000); // 1초 이내
});

주의사항

1. 프로덕션 코드에서 사용 금지

// ❌ 프로덕션 코드에서 Naite 사용하지 말 것
class UserModelClass extends BaseModel {
  async createUser() {
    Naite.t("user.create", data); // ❌ 테스트 전용!
    return this.save(data);
  }
}

2. 민감한 정보 로깅 주의

test("로그 주의사항", async () => {
  // ❌ 비밀번호 같은 민감 정보 로깅하지 말 것
  Naite.t("user.create", { 
    email,
    password  // ❌
  });
  
  // ✅ 민감 정보 제외
  Naite.t("user.create", { 
    email,
    hasPassword: !!password  // ✅
  });
});

3. 과도한 로깅 피하기

// ❌ 루프 안에서 과도한 로깅
for (let i = 0; i < 1000; i++) {
  Naite.t(`item.${i}`, data); // ❌ 너무 많음
}

// ✅ 요약 로깅
Naite.t("items.processed", { 
  count: 1000,
  sample: items.slice(0, 3)  // ✅ 샘플만
});

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

Naite란?

기본 사용법

1. 로그 기록하기

2. 로그 조회하기

디버깅 패턴

API 요청/응답 추적

데이터베이스 쿼리 추적

비즈니스 로직 흐름 추적

로그 키 네이밍 규칙

조건부 로깅

Model에서 Naite 사용

로그 쿼리

NaiteQuery 메서드

Naite Viewer 사용

디버깅 워크플로우

1. 테스트 실패 시

2. 로그 분석

3. 특정 시나리오 재현

성능 디버깅

주의사항

1. 프로덕션 코드에서 사용 금지

2. 민감한 정보 로깅 주의

3. 과도한 로깅 피하기

관련 문서

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​Naite란?

​기본 사용법

​1. 로그 기록하기

​2. 로그 조회하기

​디버깅 패턴

​API 요청/응답 추적

​데이터베이스 쿼리 추적

​비즈니스 로직 흐름 추적

​로그 키 네이밍 규칙

​조건부 로깅

​Model에서 Naite 사용

​로그 쿼리

​NaiteQuery 메서드

​Naite Viewer 사용

​디버깅 워크플로우

​1. 테스트 실패 시

​2. 로그 분석

​3. 특정 시나리오 재현

​성능 디버깅

​주의사항

​1. 프로덕션 코드에서 사용 금지

​2. 민감한 정보 로깅 주의

​3. 과도한 로깅 피하기

​관련 문서

Naite란?

기본 사용법

1. 로그 기록하기

2. 로그 조회하기

디버깅 패턴

API 요청/응답 추적

데이터베이스 쿼리 추적

비즈니스 로직 흐름 추적

로그 키 네이밍 규칙

조건부 로깅

Model에서 Naite 사용

로그 쿼리

NaiteQuery 메서드

Naite Viewer 사용

디버깅 워크플로우

1. 테스트 실패 시

2. 로그 분석

3. 특정 시나리오 재현

성능 디버깅

주의사항

1. 프로덕션 코드에서 사용 금지

2. 민감한 정보 로깅 주의

3. 과도한 로깅 피하기

관련 문서