로그 파일 정책

#폴더 구조

logs/
└── YYYY-MM-DD/
    ├── 00_INDEX.txt          ← 증상 → 볼 파일 안내 (자동 생성)
    ├── 01_INTEGRATED/
    ├── 02_CLUSTER/
    │   ├── _CLUSTER-2026-10-27.log   ← 소량 모듈 통합 파일
    │   └── BUFFER-2026-10-27.log     ← 대용량 모듈 개별 파일
    ├── 03_EZIIO/
    └── ...

• 날짜 폴더 안에서 도메인별로 나눕니다.
• 각 날짜 폴더에 증상 → 볼 파일 안내 파일을 자동으로 만들어 둡니다.

왜 — 장애가 났을 때 "어느 날, 어느 도메인"부터 좁혀 들어가는 것이 가장 빠릅니다. 한 폴더에 수백 개 파일이 쌓이면 찾는 데만 시간이 걸립니다.

#경로는 한 모듈에서만 만든다

로그 경로와 카테고리를 정하는 단일 출처 모듈을 하나 두고, 다른 곳에서는 경로를 직접 조립하지 않습니다.

// O — 모듈 이름만 넘기면 카테고리·경로는 공용 모듈이 정한다
const log = (...args) => logToFile(path.basename(__filename, '.js'), ...args);

// X — 경로를 직접 조립
fs.appendFileSync(path.join(logDir, 'my.log'), msg);

• 파일(모듈) 이름이 곧 로그 접두사가 되고, 공용 모듈이 카테고리를 자동으로 정합니다.
• 규칙에 없는 새 접두사는 미분류(99_ETC) 로 가고 경고가 1회 남습니다. 이 경고를 보면 분류 규칙에 반드시 추가합니다.
• 파일에 직접 써야 할 때도 경로는 공용 모듈에서 받습니다. 공용 모듈이 폴더를 만들어 주기 때문입니다.

왜 — 날짜 폴더가 아직 없을 때 직접 쓰면 "폴더 없음(ENOENT)" 오류로 로그가 통째로 사라집니다.

#카테고리 — 번호 = 조사 순서

번호 순서대로 보면 통합 흐름 → 판정 → 물리 동작 → 통신 원문 순으로 원인을 좁힐 수 있습니다.

#개별 파일과 통합 파일

• 대용량이거나 장애 때 통째로 읽는 핵심 로그만 자기 파일을 갖습니다. (기준 예: 하루 1MB 이상)
• 나머지 소량 모듈은 카테고리 통합 파일(_<카테고리>-날짜.log)에 [모듈명] 태그와 함께 합칩니다.

# 통합 파일에서 특정 모듈만 보기
grep "\[gateComControl\]" _GATE-2026-10-27.log

#보존

• 보존 로직은 한 모듈에만 둡니다. 새로 만들지 않습니다.
• 날짜 폴더 단위로, 정한 기간(예: 15일)이 지나면 폴더째 삭제합니다.
• 여러 로그 출력기가 보존 장부(audit 파일)를 공유하지 않게 합니다 — 서로 덮어써서 보존이 깨집니다.

#로그에 남기지 않는 것

• 비밀번호·토큰·키 등 비밀값
• 필요 이상의 개인정보(전화번호 전체 등). 꼭 필요하면 일부를 가립니다.

자세한 내용은 '보안 기본 규칙' 문서를 참조하세요.