Node.js 프로파일링: CPU 프로파일과 플레임 그래프 읽기

--cpu-prof, Chrome DevTools, Inspector, Linux perf로 Node.js CPU 핫스폿을 찾습니다. 플레임 그래프와 타임라인의 차이, 지속적 프로파일링의 조건도 살펴봅니다.

모범 사례
Node.js 이벤트 루프와 비동기 작업 흐름을 나타낸 일러스트

Node.js의 CPU 사용률이 높아도 가장 느린 요청은 데이터베이스 응답을 기다리고 있을 수 있습니다. CPU에서 실행한 작업과 기다린 시간은 나누어 봐야 합니다. 실행 시간이 어디에 쓰이는지 확인하려면 node --cpu-prof app.js로 시작하고, 생성된 .cpuprofile을 Chrome DevTools에서 엽니다. 지속적 프로파일링을 함께 쓰면 실제로 수집하고 보관한 운영 구간과도 비교할 수 있습니다.

CPU 작업과 I/O 대기를 구분하기

높은 CPU 사용률은 비즈니스 코드뿐 아니라 GC, 네이티브 모듈, 커널 작업에서도 발생합니다. 먼저 사용자 CPU, 시스템 CPU, 프로세스 부하를 확인하고 도구를 고릅니다. 시스템 부하가 높다는 말이 CPU 사용률이 높다는 뜻은 아닙니다. I/O 대기, 연결 고갈, 느린 의존 서비스도 JavaScript CPU 핫스폿 없이 요청을 지연시킬 수 있습니다.

CPU 프로파일은 샘플로 포착한 실행을 설명합니다. 요청이 얼마나 기다렸고 어느 의존 서비스에서 지체됐는지는 호스트 메트릭과 분산 추적을 함께 봐야 합니다.

내장 Profiler로 수집하기

node --cpu-prof app.js          # 시작할 때부터 샘플링하고 정상 종료 시 저장
# 또는 출력 디렉터리를 지정해서 시작
mkdir -p /tmp/profiles
node --cpu-prof --cpu-prof-dir=/tmp/profiles app.js

두 node 명령 중 하나를 선택합니다. 둘 다 프로세스 시작 시점부터 샘플링합니다. --cpu-prof-dir은 저장 위치를 바꾸는 옵션이며, 실행 중인 프로세스에 필요할 때 연결하는 기능이 아닙니다. 첫 번째 명령은 기본적으로 작업 디렉터리에 저장하며 --diagnostic-dir로 바꿀 수 있습니다. 두 번째는 /tmp/profiles에 쓸 수 있어야 합니다. 디렉터리 명령은 Unix 계열 셸 기준이므로 다른 플랫폼에서는 알맞은 경로를 사용합니다.

애플리케이션을 정상 종료한 뒤 .cpuprofile을 찾습니다. SIGKILL이나 실행 환경의 강제 종료로 끝난 프로세스가 파일을 완전히 기록한다고 보장할 수는 없습니다. 상시 실행 서비스에서 수집 구간을 제한하려면 Inspector 녹화를 사용할 수 있습니다.

별도 내장 옵션인 --prof는 V8 로그를 만들고 --prof-process로 처리합니다. 이 출력은 .cpuprofile이 아니므로 수집 형식과 분석 절차를 혼용하지 않습니다.

Chrome DevTools에서 결과 읽기

.cpuprofile은 Performance 패널에 불러옵니다. 오래된 가이드의 JS Profiler 패널은 지원 중단 대상으로 지정됐으며, 현재 절차는 Performance를 사용합니다.

  • **플레임 차트(flame chart)**의 가로축은 녹화 시간입니다. 핫스폿이 어느 구간에서 나타났는지 볼 수 있습니다. 반면 집계형 **플레임 그래프(flame graph, flamegraph)**는 같은 스택을 합칩니다. 가로 위치는 발생 순서가 아니며 너비는 샘플 가중치나 그에 해당하는 시간 비중을 나타냅니다.
  • 넓은 프레임에는 하위 호출의 작업도 포함됩니다. 위쪽에 넓게 드러난 부분은 단서가 되지만 부모 프레임의 너비만으로 함수 자체가 느리다고 판단하면 안 됩니다. Self Time은 자체 실행 시간이고 Total Time은 하위 호출까지 포함한 시간입니다.
  • Bottom-Up은 선택한 구간의 활동 시간을 집계합니다. Self Time이나 Total Time으로 정렬한 다음 호출 관계를 따라 코드로 돌아갑니다. 파일과 줄까지 연결되는지는 소스와 source map을 사용할 수 있는지에 달려 있습니다.

Inspector와 Linux perf로 다른 실행 영역 보기

Inspector는 재현 과정을 보면서 수집 구간을 제어하기에 적합합니다. 통제된 디버깅 환경에서 node --inspect app.js로 실행하고 chrome://inspect에서 연결한 뒤 Performance에서 녹화를 시작하고 멈춥니다. 기본 수신 주소는 127.0.0.1:9229입니다. 연결한 디버거는 애플리케이션 실행 환경을 제어할 수 있으므로 인터넷에 포트를 공개하지 않고, 원격 접속은 통제된 터널 등을 사용합니다.

Linux perf는 JavaScript 위주의 화면으로 설명하기 어려운 네이티브 모듈, V8, 커널의 실행 비용을 조사하는 데 도움이 됩니다. 기존 대상 프로세스에 perf record -F 99 -p <pid> -g를 사용하면 99 Hz 샘플링과 호출 체인 기록을 요청합니다. 수집을 마치면 perf를 멈추고 perf script 같은 도구로 처리합니다.

환경에 맞는 Linux perf, 대상 샘플링 권한, 풀어낼 수 있는 호출 스택이 필요합니다. JavaScript 함수 이름을 읽으려면 Node를 시작할 때 --perf-basic-prof-only-functions, --interpreted-frames-native-stack 같은 플래그를 설정하고 JIT 매핑과 네이티브 심벌을 사용할 수 있어야 할 수도 있습니다. 결과는 Node/V8, 커널, 컨테이너 권한에 따라 달라집니다. 기본 설정에서 완전한 JS 스택이 보인다고 가정하거나, 예제를 실행하려고 시스템 전체의 샘플링 권한을 완화해서는 안 됩니다.

지속적 프로파일링으로 운영 구간 비교하기

운영에서 발생한 문제는 나중에 다시 재현하기 어려울 수 있습니다. 지속적 프로파일링은 설정한 기간 동안 샘플링을 이어 가며, 이미 수집했고 보존 기간이 남은 Profile로 성능 저하 전후의 호출 스택을 비교하게 해 줍니다.

Profile은 메트릭, 로그, 트레이스에 더하는 신호입니다. 수집을 켜기 전이나 빠진 구간을 복원하지는 않으며, 목적을 정한 수동 녹화와 함께 사용합니다. 수집 범위와 오버헤드는 프로파일 유형, 빈도, 워크로드에 따라 달라지므로 언제나 일정한 저비용이라고 단정할 수 없습니다.

핫스폿과 요청 동작을 함께 확인하기

로컬 CPU 프로파일에서 찾은 핫스폿도 운영 부하 안에서 확인해야 합니다. Guance의 Node.js Profiling 문서는 Pyroscope를 통한 수집 경로를 설명합니다. 애플리케이션에 @pyroscope/nodejs를 넣고 DataKit에서 별도로 Profile 수신을 활성화합니다. 서비스, 환경, 버전 필드를 설정하면 같은 배포의 샘플을 일관된 조건으로 필터링할 수 있습니다.

SDK의 serverAddress는 애플리케이션이 접근할 수 있는 DataKit Pyroscope 수신 주소를 가리켜야 합니다. 실제 배포할 DataKit, SDK, Node.js 버전과 운영체제, 필요한 프로파일 유형을 함께 확인합니다. 현재 Pyroscope SDK 문서는 CPU 수집에 wall.collectCpuTime을 명시적으로 활성화하도록 요구합니다. 기본 wall 프로파일은 CPU 프로파일과 같은 측정값이 아닙니다.

APM과 Profiling은 데이터 수집 경로가 다릅니다. APM만 켜도 함수 단위 Profile이 모이는 것은 아니며, 서비스 필드가 같다고 Span별 연결까지 자동으로 이뤄지는 것도 아닙니다. 먼저 스테이징에서 수집 오버헤드를 측정한 뒤 같은 버전과 비슷한 부하에서 핫스폿과 요청 지연을 비교합니다.

설정 문서: Node.js Profiling(영어), Node.js APM(영어), Pyroscope Node.js SDK(영어).

자주 묻는 질문

프로파일링 오버헤드는 얼마나 큰가요?

워크로드, 샘플링 빈도, 분석 옵션에 따라 다릅니다. 운영 수집 구간을 정하기 전에 스테이징에서 처리량, 지연, 메모리를 비교합니다. 지속적 프로파일링도 별도로 설정하고 평가해야 합니다.

플레임 그래프는 어디부터 읽어야 하나요?

Self Time으로 자체 실행 비용이 큰 프레임을 찾고, JavaScript·네이티브·GC 프레임을 구분한 뒤 정상 구간과 비교합니다. GC 비중이 높다면 가비지 컬렉션이 실행 시간을 많이 사용한 것입니다. 잦은 할당, 객체 수명, 힙 설정 등이 원인일 수 있지만 그것만으로 메모리 누수라고 판단할 수는 없습니다. 많은 할당을 일으키는 비즈니스 알고리즘도 여전히 확인 대상입니다.

비동기 코드의 CPU 시간은 어떻게 기록되나요?

이벤트 루프 콜백은 여러 tick에 걸쳐 실행됩니다. CPU 프로파일은 그때 샘플링한 실행 스택을 기록하며, 데이터베이스를 await한 전체 대기 시간을 함수 자체의 CPU 시간으로 계산하지 않습니다. 종단 간 소요 시간과 의존 서비스 대기는 추적으로 확인합니다. wall 시간이나 off-CPU를 분석하려면 해당 유형을 지원하는 수집기가 필요하며, CPU 프로파일만으로 도출할 수는 없습니다.


참고 문서

이 글은 공개 문서를 바탕으로 작성했습니다. 예제는 프로젝트의 의존성 버전에 맞춰 검증해야 하며, 문서의 성능 설명을 이 프로젝트에서 직접 측정한 결과로 제시하지 않습니다.

관련 글

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소