perf_hooks와 Prometheus로 Node.js 성능 모니터링하기
Node.js 코드 구간을 측정하고 이벤트 루프 지연과 사용률을 구분한 뒤, Prometheus에서 라우트별 P95 지연을 조회합니다.
주문 API가 느려져도 평균 응답 시간은 거의 그대로일 수 있습니다. 특정 라우트에서 유난히 늦은 응답이 늘었다면, 어느 작업에서 기다렸는지와 그동안 이벤트 루프가 움직일 수 있었는지를 따로 살펴봐야 합니다. Node.js 성능 모니터링에서는 코드 구간, 런타임 상태, 요청 지연 시간을 서로 다른 관측 지점으로 삼습니다.
요청이 기다린 구간 재기
데이터베이스 쿼리나 외부 API 호출을 감싸서 재면 대기 시간을 포함한 경과 시간이 나옵니다. 데이터 변환, 템플릿 렌더링, JSON 직렬화처럼 CPU를 쓰는 작업은 각각 재어 병목을 좁힙니다. 예를 들어 커넥션 풀에서 연결을 빌리는 시간이 포함된 애플리케이션의 측정값과 데이터베이스 내부의 쿼리 실행 시간은 범위가 다릅니다.
다음 CommonJS 예제는 PerformanceObserver를 먼저 등록합니다. 호출마다 별도의 시작 마크를 남기므로 쿼리를 동시에 실행해도 시작 시각이 덮어쓰이지 않습니다. 측정 이름은 고정하고, 사용을 마친 항목은 타임라인에서 지웁니다.
const { performance, PerformanceObserver } = require('node:perf_hooks');
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntriesByName('db-query')) {
console.log('db-query', entry.duration);
}
});
observer.observe({ entryTypes: ['measure'] });
let sequence = 0;
async function timeQuery(query) {
const start = 'db-query:start:' + (++sequence);
performance.mark(start);
try {
return await query();
} finally {
performance.measure('db-query', { start, end: performance.now() });
performance.clearMarks(start);
performance.clearMeasures('db-query');
}
}
비동기 함수에서 프로젝트의 데이터베이스 클라이언트를 사용해 await timeQuery(() => db.query(sql))처럼 호출합니다. 실패한 쿼리의 시간도 남기고 오류는 호출자에게 그대로 전달합니다. entry.duration의 단위는 밀리초입니다. 초 단위 히스토그램에 기록할 때는 1,000으로 나눕니다. 메트릭 이름은 고정하고 라벨 값은 쿼리 작업 유형처럼 범위가 정해진 값으로 제한합니다. 측정값을 하나씩 출력하는 것은 디버깅할 때만 쓰고, 측정을 중단할 때는 옵저버를 해제합니다.
이벤트 루프 지연과 사용률을 함께 보기
이벤트 루프 지연은 샘플링 타이머가 얼마나 늦게 실행됐는지를 보여 줍니다. 이벤트 루프 사용률(ELU)은 관측 구간 중 루프가 유휴 대기 외의 상태에 머문 비율입니다. 동기 호출이 메인 스레드를 막으면 프로세스의 CPU 사용률이 낮아도 ELU는 높아질 수 있습니다. 다음 예제는 두 스냅샷의 차이로 구간별 ELU를 계산합니다. 지연 히스토그램의 나노초 값을 밀리초로 바꾸고 구간마다 히스토그램을 초기화합니다. unref()를 호출하면 다른 작업이 없을 때 이 타이머 때문에 프로세스가 계속 실행되지 않습니다.
const { performance, monitorEventLoopDelay } = require('node:perf_hooks');
const delay = monitorEventLoopDelay({ resolution: 20 });
delay.enable();
let previous = performance.eventLoopUtilization();
const timer = setInterval(() => {
const current = performance.eventLoopUtilization();
const delta = performance.eventLoopUtilization(current, previous);
previous = current;
const p99Ms = delay.count ? delay.percentile(99) / 1e6 : null;
delay.reset();
console.log({ utilization: delta.utilization, p99Ms });
}, 10_000);
timer.unref();
function stopSampling() {
clearInterval(timer);
delay.disable();
}
서비스 안에서 샘플러를 실행하고 종료할 때 stopSampling()을 호출합니다. 지연은 같은 샘플링 간격으로 측정한 평상시 값과 비교합니다. 요청 지연과 함께 늘었다면 CPU 집약적인 작업, 동기 호출, 가비지 컬렉션(GC)의 정지 시간을 확인합니다. GC 시간만으로 메모리가 계속 쌓인다고 판단하기 어려우므로 힙 사용량의 추이도 함께 봅니다. 요청만 느려졌다면 데이터베이스 연결 대기나 외부 의존성을 확인할 차례입니다. 워커 스레드마다 이벤트 루프가 있어 메인 스레드 측정값만으로는 워커 안의 지연을 볼 수 없습니다. CPU 집약적인 JavaScript를 워커에서 실행할 때는 작업 분배와 데이터 전달에 드는 비용도 고려합니다.
요청과 런타임 메트릭을 한 엔드포인트로 노출하기
Express 예제는 이전 패키지 이름인 prom-client@15.1.3을 사용합니다. 후속 버전은 @prometheus-io/client로 배포되므로 업그레이드할 때 변경 이력을 확인하세요. 주문 라우트 핸들러에서 타이머를 시작하고, Node.js가 응답을 전송할 수 있도록 운영체제에 넘기면 finish 이벤트가 발생합니다. 중간에 연결이 끊긴 요청이나 클라이언트가 체감한 지연은 필요에 따라 따로 측정합니다.
const express = require('express');
const client = require('prom-client');
const app = express();
const registry = new client.Registry();
client.collectDefaultMetrics({ register: registry });
const httpDuration = new client.Histogram({
name: 'http_request_duration_seconds',
help: 'Duration of completed HTTP responses in seconds',
labelNames: ['method', 'route', 'status'],
buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 2, 5],
registers: [registry],
});
const orderRoute = '/api/orders/:id';
app.get(orderRoute, (req, res) => {
const end = httpDuration.startTimer();
res.once('finish', () => end({
method: req.method,
route: orderRoute,
status: String(res.statusCode),
}));
res.json({ ok: true });
});
app.get('/metrics', async (_req, res, next) => {
try {
const body = await registry.metrics();
res.set('Content-Type', registry.contentType).end(body);
} catch (error) {
next(error);
}
});
app.listen(3000, '127.0.0.1');
Express와 예제에 명시한 클라이언트를 설치한 뒤 파일을 실행합니다. http://127.0.0.1:3000/api/orders/42를 호출하고 http://127.0.0.1:3000/metrics의 결과를 확인합니다. 주문 ID가 바뀌어도 라벨은 /api/orders/:id로 유지됩니다. 프로세스와 Node.js의 기본 메트릭도 HTTP 히스토그램과 같은 레지스트리에 들어갑니다. 예제는 루프백 주소에서만 연결을 받습니다. 운영에서는 허용한 모니터링 인프라에서만 엔드포인트에 접근할 수 있게 합니다. 복제본은 개별 수집 대상으로 삼고, Node.js의 cluster 모듈을 쓰면 워커 프로세스 집계를 따로 설정합니다.
여러 인스턴스에서 라우트별 꼬리 지연 조회하기
히스토그램에는 버킷별 누적 건수가 기록됩니다. 아래 쿼리는 node-api라는 Prometheus 스크레이프 작업에서 5분 동안의 라우트별 P95를 여러 인스턴스에 걸쳐 추정합니다. 집계 전에 rate를 적용해야 개별 시계열의 카운터 초기화를 처리할 수 있습니다. le는 버킷의 상한을 유지하는 라벨입니다.
histogram_quantile(
0.95,
sum by (route, le) (
rate(http_request_duration_seconds_bucket{job="node-api"}[5m])
)
)
P95 옆에는 http_request_duration_seconds_count의 요청률도 표시합니다. 표본이 적으면 전체 분포가 달라지지 않았는데도 추정값이 크게 움직일 수 있습니다. 클래식 히스토그램은 버킷 안에서 보간해 백분위수를 구하므로, 응답 시간 기준에 맞는 경계를 정하고 복제본에 같은 경계를 적용합니다. 300ms 안에 끝난 응답 비율은 같은 범위와 시간 구간에서 le="0.3" 버킷의 증가율을 _count 증가율로 나누면 됩니다. 5xx 비율도 전체 요청률을 분모로 삼되, 오류 시계열이 아직 없는 경우와 요청 자체가 없는 구간을 구분합니다.
느린 라우트에서 의존성까지 따라가기
주문 라우트의 P95만 늘고 이벤트 루프 지연과 GC가 평소 수준이라면, 느린 요청의 트레이스에서 시간을 어디에 썼는지 확인합니다. 데이터베이스 연결 대기가 길어졌다면 쿼리를 바꾸기 전에 커넥션 풀이 포화됐는지 살펴봅니다. 반대로 한 인스턴스의 여러 라우트에서 요청 지연과 이벤트 루프 지연이 함께 늘었다면, 해당 프로세스의 작업부터 조사합니다.
Guance에서는 DataKit Prom 수집기(영어)로 메트릭을 스크레이프하고, 별도로 구성한 Node.js APM 계측(영어)으로 트레이스를 보낼 수 있습니다. 서비스, 환경, 인스턴스 식별자를 맞춰 두면 같은 배포의 메트릭과 트레이스를 같은 시간대에서 비교할 수 있습니다.
