Node.js diagnostic report로 멈춘 process의 상태를 남기는 법

재시작 전에 증거가 사라지는 문제

Node.js process가 응답하지 않아 재시작했지만 당시 JavaScript stack, 열린 socket과 heap 상태를 남기지 못했습니다. 일반 application log만으로 event loop와 native resource 상태를 복원하기 어려울 때 diagnostic report 수집을 준비할 수 있습니다.

Node.js diagnostic report는 JavaScript·native stack, V8 heap, libuv handle, OS와 resource 정보를 담지만 환경변수와 network 정보도 포함할 수 있어 저장 위치와 접근 권한을 제한해야 합니다.

안전하게 수집하는 흐름

운영에서는 report directory를 용량과 권한이 제한된 전용 경로로 정합니다. Linux와 macOS에서는 --report-on-signal의 기본 signal인 SIGUSR2로 필요할 때 report를 만들 수 있고, Windows에서는 signal trigger가 지원되지 않으므로 API나 다른 trigger를 사용합니다.

node --report-on-signal \
  --report-directory=/var/log/my-app/reports \
  --report-exclude-env \
  --report-exclude-network app.js

kill -USR2 <node-pid>

Node 22.13.0 이상에서는 --report-exclude-env로 환경변수를, Node 20.13.0 또는 22.0.0 이상에서는 --report-exclude-network로 network 정보를 제외할 수 있습니다.

report를 원인과 연결하기

생성 시각과 PID를 load balancer, application latency, CPU·RSS 지표와 같은 timeline에 놓습니다. javascriptStack, javascriptHeap, libuv handle이 현재 가설과 일치하는지 확인하되 report 한 장만으로 memory leak이나 deadlock을 단정하지 않습니다. 파일은 secret과 같은 등급으로 접근을 제한하고 보존 기한을 둡니다. staging에서 signal, 쓰기 권한, disk quota와 수집 시간을 검증한 뒤 운영에 적용합니다.

공식 문서

• Node.js: Diagnostic report (새 창에서 열림)

배포한 Node.js version에서 지원 flag와 report schema, 민감정보 제외 범위를 확인합니다.