Node.js를 Prometheus로 모니터링하기

Express 런타임과 HTTP 메트릭을 수집하고 PromQL로 요청 처리율, 5xx 비율, P95를 조회합니다. 요청이 적을 때를 고려한 알림 규칙도 설정합니다.

모범 사례
Node.js 이벤트 루프 그림

결제 API가 503을 반환하기 시작했는데 CPU와 힙 사용량은 평소와 같을 수 있습니다. 먼저 확인할 것은 실패한 요청이 얼마나 되는지, 완료된 응답의 처리 시간이 전반적으로 늘었는지입니다. Node.js용 Prometheus 클라이언트를 사용하면 런타임 메트릭과 이 질문에 답하기 위해 추가한 카운터, 히스토그램을 같은 /metrics 엔드포인트로 노출할 수 있습니다.

이 글에서는 Express의 결제 라우트 하나를 계측하고, Prometheus로 수집한 뒤 알림 규칙 두 개를 설정합니다. 결제 응답은 설명용으로 만든 예시입니다.

애플리케이션에 스크레이프 엔드포인트 만들기

Prometheus는 일정한 간격으로 애플리케이션에서 메트릭을 가져옵니다. 메트릭 이름과 레이블 조합이 시계열 하나를 식별하고, 스크레이프가 성공할 때마다 샘플이 추가됩니다. Prometheus는 PromQL 쿼리와 알림 규칙을 평가하고, Alertmanager는 알림을 알맞은 채널로 보냅니다. 시각화에는 Grafana를 사용할 수 있습니다.

이 클라이언트의 이전 패키지 이름은 prom-client입니다. 예제는 후속 패키지인 @prometheus-io/client 0.16.1과 Node.js 22를 사용합니다. 이 버전의 패키지는 Node.js 22, 24, 26 이상을 지원합니다. 별도의 테스트 프로젝트에 의존성을 설치합니다.

npm install express@5.3.0 @prometheus-io/client@0.16.1

다음 코드를 checkout.cjs에 저장하고 node checkout.cjs로 실행합니다. 루프백 주소는 로컬 테스트용입니다. 배포 환경에서는 수집기가 제어된 네트워크 경로로 /metrics에 접근할 수 있게 하고, 그 밖의 접근을 제한합니다.

const express = require('express');
const client = require('@prometheus-io/client');

const app = express();
client.collectDefaultMetrics();
const requests = new client.Counter({
  name: 'http_requests_total',
  help: 'Completed checkout HTTP responses',
  labelNames: ['method', 'route', 'status'],
});
const inFlight = new client.Gauge({
  name: 'http_requests_in_flight',
  help: 'Checkout HTTP responses still in progress',
});
const duration = new client.Histogram({
  name: 'request_duration_seconds',
  help: 'Completed checkout response duration in seconds',
  labelNames: ['route'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
});

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', client.register.contentType);
  res.end(await client.register.metrics());
});

const checkoutRoute = '/checkout';
for (const status of ['204', '503']) {
  requests.inc({ method: 'POST', route: checkoutRoute, status }, 0);
}

app.post(checkoutRoute, (req, res) => {
  const route = checkoutRoute;
  const stopTimer = duration.startTimer({ route });
  inFlight.inc();

  res.once('finish', () => {
    requests.inc({ method: req.method, route, status: String(res.statusCode) });
    stopTimer();
  });
  res.once('close', () => inFlight.dec());

  res.status(req.query.fail === '1' ? 503 : 204).end();
});

app.listen(3000, '127.0.0.1');
curl -i -X POST 'http://127.0.0.1:3000/checkout'
curl -i -X POST 'http://127.0.0.1:3000/checkout?fail=1'
curl -fsS http://127.0.0.1:3000/metrics

위 요청은 각각 204와 503을 반환합니다. 쿼리 파라미터는 예제에서 실패를 재현하는 용도입니다. 이후 스크레이프 결과에는 http_requests_total의 상태 코드 두 가지와, 완료된 응답 두 건을 센 request_duration_seconds_count가 나타납니다. 기본 메트릭에는 이벤트 루프 지연, 가비지 컬렉션, 힙 사용량, CPU 등이 포함됩니다. 일부 메트릭은 실행 플랫폼에 따라 달라집니다.

알고 싶은 것에 맞춰 메트릭 고르기

**카운터(Counter)**는 메서드, 라우트, 상태 코드별로 완료한 응답을 셉니다. 프로세스가 재시작되면 값이 초기화됩니다. 최종 상태 코드는 응답의 finish 이벤트에서 읽습니다. 이 이벤트는 데이터를 운영체제에 넘겨 전송할 준비가 됐을 때 발생하므로, 예제는 라우트 처리 시작부터 서버 쪽 시간만 측정합니다. 클라이언트까지 걸리는 네트워크 시간은 포함되지 않습니다.

**게이지(Gauge)**는 처리 중인 응답 수를 보여 줍니다. 처리 시작 시 증가하고, close에서 감소합니다. 연결이 일찍 끊겨도 값은 줄어듭니다. finish에 도달하지 못한 응답은 완료 건수와 지연 시간 히스토그램에 포함하지 않습니다. 연결 중단을 관찰해야 한다면 별도 지표로 집계합니다.

**클래식 히스토그램(Histogram)**은 처리 시간을 누적 버킷별로 셉니다. 복제본마다 버킷 경계를 동일하게 설정하면 Prometheus가 집계한 뒤 분위수를 추정할 수 있습니다. 중요하게 보는 지연 시간 기준 주변에 경계를 배치합니다. **서머리(Summary)**는 프로세스에서 직접 분위수를 계산할 수 있습니다. 프로세스별 P95를 평균 내도 전체 요청의 P95가 되지는 않습니다.

레이블은 가능한 값의 수를 제한합니다. /orders/:id 같은 라우트에서는 주문 ID나 원본 쿼리 문자열 대신 라우트 템플릿을 기록합니다. 레이블 조합이 달라질 때마다 시계열이 추가됩니다. 히스토그램에서는 버킷과 합계, 건수도 각각 시계열을 만듭니다.

요청 처리율, 오류 비율, P95 조회하기

다음 설정을 prometheus.yml에 저장합니다. 다음 절의 알림 파일도 같은 디렉터리에 두고, 예제 앱과 같은 호스트에서 prometheus --config.file=prometheus.yml을 실행합니다.

global:
  scrape_interval: 15s
  evaluation_interval: 15s
rule_files:
  - checkout-alerts.yml
scrape_configs:
  - job_name: checkout-node
    static_configs:
      - targets: ["127.0.0.1:3000"]

첫 번째 쿼리는 라우트별로 초당 완료 응답 수를 구합니다. 두 번째는 결제 스크레이프 작업 전체의 5xx 응답 비율을 백분율로 표시합니다. 세 번째는 라우트별 P95를 초 단위로 추정합니다.

sum by (route) (rate(http_requests_total{job="checkout-node"}[5m]))
100 * (
  sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
  or 0 * sum(rate(http_requests_total{job="checkout-node"}[5m]))
) / (sum(rate(http_requests_total{job="checkout-node"}[5m])) > 0)
histogram_quantile(0.95, sum by (le, route) (
  rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
))

각 카운터 시계열에 rate()를 먼저 적용한 뒤 집계해야 Prometheus가 프로세스 재시작으로 초기화된 값을 처리할 수 있습니다. 전체 처리율을 구할 수 있는데 5xx 처리율이 비어 있으면 or 0 * ...가 분자를 0으로 채웁니다. 새로운 시계열은 샘플이 충분히 쌓여야 처리율을 계산할 수 있습니다. 예제는 두 상태 코드의 카운터를 미리 초기화해 첫 오류 전에 0을 수집할 수 있게 합니다. 트래픽이 없거나 전체 처리율을 계산할 수 없으면 분모 필터 때문에 결과가 비어 있습니다. 스크레이프 실패와 요청이 없는 상태는 up을 별도로 확인해 구분합니다.

문제가 계속될 때 알림 보내기

checkout-alerts.yml은 최근 5분의 데이터로 오류 비율과 P95를 구합니다. 규칙 평가에서 조건이 5분 동안 유지되어야 알림이 발생합니다. 요청이 너무 적은 상황에서 예제 임계값에 걸리지 않도록 최소 요청 처리율도 조건에 포함했습니다. 실제 트래픽과 SLO에 맞춰 임계값을 조정하고, 알림을 전달할 Alertmanager 대상을 Prometheus에 설정합니다.

groups:
  - name: checkout
    rules:
      - record: checkout:http_requests_per_second:rate5m
        expr: sum(rate(http_requests_total{job="checkout-node"}[5m]))
      - alert: CheckoutHighErrorRatio
        expr: |
          (
            sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
            or 0 * checkout:http_requests_per_second:rate5m
          ) / checkout:http_requests_per_second:rate5m > 0.01
          and checkout:http_requests_per_second:rate5m > 0.2
        for: 5m
      - alert: CheckoutHighP95
        expr: |
          histogram_quantile(0.95, sum by (le) (
            rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
          )) > 2
          and checkout:http_requests_per_second:rate5m > 0.2
        for: 5m

Guance에서 같은 엔드포인트 사용하기

DataKit의 Prom 수집기는 기존 /metrics를 스크레이프하여 선택한 메트릭을 Guance로 전송할 수 있습니다. 대상 주소와 필요한 인증 정보, 수집 주기를 설정합니다. 오류 비율이나 지연 시간을 모니터링하는 규칙을 만들기 전에 메트릭 유형, 단위, 레이블 매핑을 확인합니다. 지연 알림을 보고 요청의 트레이스를 살펴보려면 Node.js APM을 별도로 계측해야 합니다. 스팬에서 로그로 이동하려면 로그에 트레이스 ID와 스팬 ID를 주입하고, 서비스, 환경, 버전 필드를 트레이스의 값과 맞춥니다.

배포할 때 자주 나오는 질문

복제본이나 Node.js 워커가 여러 개면 어떻게 수집하나요?

복제본마다 개별 스크레이프 대상을 둡니다. 로드 밸런싱 주소 하나를 스크레이프하면 호출할 때마다 서로 다른 프로세스의 값이 들어올 수 있습니다. Node.js cluster를 사용한다면 워커별로 노출하거나 클라이언트의 AggregatorRegistry로 합칠 수 있습니다. Kubernetes에 Prometheus Operator가 설치되어 있다면 올바른 셀렉터와 포트를 지정하고 ServiceMonitor로 대상을 찾을 수 있습니다.

CronJob이 스크레이프 사이에 끝나면 어떻게 하나요?

특정 머신에 묶이지 않은 서비스 단위 배치 작업이라면 실행 결과나 마지막 성공 시간을 Pushgateway에 전송할 수 있습니다. Prometheus나 DataKit은 그 엔드포인트를 스크레이프합니다. Pushgateway의 그룹은 명시적으로 삭제할 때까지 남으므로 작업이 사라졌을 때 그룹을 정리해야 합니다. 특정 머신에서 실행하는 작업에는 Node Exporter의 textfile 수집기를 고려할 수 있습니다. 실행마다 개별 기록이 필요하다면 로그나 트레이스도 선택지입니다.

계측 오버헤드는 어느 정도인가요?

실제와 비슷한 트래픽에서 측정합니다. 메트릭 수, 레이블 조합 수, 히스토그램 버킷 수, 스크레이프 주기에 따라 수집 부하와 전송량이 달라집니다. 사용자 ID처럼 값의 종류가 많은 레이블은 백엔드에 저장하고 조회할 시계열 수도 늘립니다.

참고 자료

함께 읽기

맞춤형 플랜 상담

문의하기

커뮤니티 가입

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

Guance 사용해 보기

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

시작하기

Guance 요금제 선택

코드 저장소