성능 모니터링과 프로파일링

이 절에서는 NestJS 애플리케이션의 성능 모니터링(Performance Monitoring)과 프로파일링(Profiling)을 다룹니다.

애플리케이션이 배포된 후에도 성능은 계속해서 관리해야 하는 중요한 요소입니다.

사용량 패턴의 변화, 데이터 증가, 코드 변경 등으로 인해 언제든지 성능 문제가 발생할 수 있으며, 이를 조기에 발견하고 해결하기 위해서는 체계적인 모니터링과 심층적인 프로파일링이 필수적입니다.

먼저 아래 다이어그램은 성능 문제를 지표 수집, 병목 가설, 프로파일링 증거, 개선 검증의 운영 루프로 읽는 기준을 잡아줍니다.

성능 모니터링이란?

성능 모니터링과 프로파일링에서는 요청이 들어오는 위치, 책임을 맡는 계층, 실패 응답으로 나가는 지점을 분리합니다.

성능 모니터링은 애플리케이션과 인프라의 핵심 지표(메트릭)를 지속적으로 수집, 시각화하고, 비정상적인 패턴이나 임계값 초과 시 알림을 발생시키는 활동입니다.

이는 시스템의 현재 상태를 파악하고, 잠재적인 문제를 사전에 감지하며, 장애 발생 시 원인을 빠르게 진단하는 데 도움을 줍니다.

• 시스템 리소스 (System Resources)
  • CPU 사용률: 프로세서가 얼마나 바쁜지 나타냅니다.
  • 메모리 사용량: 애플리케이션이 사용하는 RAM의 양입니다. 메모리 누수는 치명적일 수 있습니다.
  • 디스크 I/O: 디스크 읽기/쓰기 작업량입니다. 데이터베이스나 파일 시스템에 많이 의존하는 경우 중요합니다.
  • 네트워크 I/O: 네트워크를 통한 데이터 송수신량입니다.
• 애플리케이션 성능 (Application Performance)
  • 응답 시간(Latency): 요청이 서버에 도달한 뒤 클라이언트가 응답을 받기까지 걸리는 시간입니다.
  • 처리량(Throughput): 단위 시간당 처리되는 요청의 수 (QPS: Queries Per Second, RPS: Requests Per Second).
  • 에러율(Error Rate): 전체 요청 중 실패한 요청의 비율입니다.
  • 동시 사용자 수: 동시에 시스템을 사용하고 있는 사용자 또는 연결 수.
  • 큐 길이: 메시지 큐나 작업 큐에 대기 중인 항목의 수.
• 데이터베이스 성능 (Database Performance)
  • 쿼리 실행 시간: 각 쿼리가 실행되는 데 걸리는 시간입니다. 느린 쿼리 식별에 중요합니다.
  • 연결 수: 데이터베이스에 연결된 클라이언트 수.
  • 잠금(Locks): 데이터베이스 잠금 발생 여부 및 시간.
  • 캐시 히트율: 데이터베이스 캐시의 효율성 지표.

• 클라우드 제공업체 모니터링 서비스: AWS CloudWatch, Google Cloud Monitoring, Azure Monitor 등.
• APM (Application Performance Monitoring) 도구: New Relic, Datadog, Dynatrace, Elastic APM 등. 코드 레벨에서의 성능 분석, 분산 트레이싱 등을 제공합니다.
• 오픈 소스 모니터링 스택: Prometheus (메트릭 수집), Grafana (시각화), Alertmanager (알림).

NestJS 성능 모니터링 구현

NestJS 애플리케이션의 성능을 모니터링하기 위해 메트릭을 노출하고 이를 Prometheus와 Grafana로 시각화하는 방법을 예시로 들어보겠습니다.

메트릭 노출

Node.js 애플리케이션의 메트릭을 Prometheus가 수집할 수 있는 형태로 노출하려면 prom-client 라이브러리를 사용할 수 있습니다.

npm install prom-client

prom-client는 TypeScript 선언을 함께 제공하므로 별도의 @types/prom-client 패키지는 필요하지 않습니다.

import { Injectable } from '@nestjs/common';
import * as client from 'prom-client';

@Injectable()
export class MetricsService {
  private readonly register = new client.Registry();
  private readonly httpRequestDurationSeconds: client.Histogram<string>;
  private readonly totalRequests: client.Counter<string>;

  constructor() {
    // 기본 메트릭 수집 활성화 (Node.js 프로세스 관련)
    client.collectDefaultMetrics({ register: this.register });

    // HTTP 요청 응답 시간 히스토그램
    this.httpRequestDurationSeconds = new client.Histogram({
      name: 'http_request_duration_seconds',
      help: 'Duration of HTTP requests in seconds',
      labelNames: ['method', 'route', 'code'] as const,
      buckets: [0.1, 0.5, 1, 2, 5], // 100ms, 500ms, 1s, 2s, 5s 버킷
      registers: [this.register],
    });

    // 총 요청 수 카운터
    this.totalRequests = new client.Counter({
      name: 'http_requests_total',
      help: 'Total number of HTTP requests',
      labelNames: ['method', 'route', 'code'] as const,
      registers: [this.register],
    });
  }

  // HTTP 요청을 기록하는 메서드
  recordHttpRequest(method: string, route: string, code: number, durationMs: number) {
    this.httpRequestDurationSeconds
      .labels(method, route, code.toString())
      .observe(durationMs / 1000); // 밀리초를 초로 변환
    this.totalRequests
      .labels(method, route, code.toString())
      .inc();
  }

  getContentType(): string {
    return this.register.contentType;
  }

  // Prometheus가 스크랩할 수 있도록 메트릭을 문자열로 반환
  async getMetrics(): Promise<string> {
    return this.register.metrics();
  }
}

Prometheus 서버가 메트릭을 가져갈 수 있는 엔드포인트를 제공합니다.

import { Controller, Get, Res } from '@nestjs/common';
import type { Response } from 'express';
import { MetricsService } from './metrics.service';

@Controller('metrics')
export class MetricsController {
  constructor(private readonly metricsService: MetricsService) {}

  @Get()
  async getMetrics(@Res() response: Response): Promise<void> {
    // Prometheus 메트릭 포맷으로 응답
    response.set('Content-Type', this.metricsService.getContentType());
    response.end(await this.metricsService.getMetrics());
  }
}

이 컨트롤러는 Express 어댑터의 Response를 사용하는 예제입니다. 운영 환경에서는 /metrics를 내부 네트워크나 인증된 수집 경로로 제한합니다.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { MetricsService } from './metrics.service';
import type { Request, Response } from 'express';

@Injectable()
export class HttpMetricsInterceptor implements NestInterceptor {
  constructor(private readonly metricsService: MetricsService) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const startedAt = Date.now();
    const httpContext = context.switchToHttp();
    const request = httpContext.getRequest<Request>();
    const response = httpContext.getResponse<Response>();
    // raw URL 대신 bounded route template을 label로 사용
    const route = request.route?.path ?? 'unmatched';

    // 성공과 예외 응답 모두 최종 status로 한 번만 기록
    response.once('finish', () => {
      this.metricsService.recordHttpRequest(
        request.method,
        route,
        response.statusCode,
        Date.now() - startedAt,
      );
    });

    return next.handle();
  }
}

이 인터셉터의 계측 범위는 인터셉터까지 진입해 finish가 발생한 응답입니다. Nest 요청 수명에서 Guard는 인터셉터보다 앞에 실행되므로 Guard가 거절한 403이나 handler를 찾지 못한 404는 이 코드로 전체 집계되지 않습니다. 진입 뒤 Pipe·handler에서 생긴 예외 응답은 응답 종료 때 기록할 수 있습니다. 따라서 코드의 성공·예외 기록 주석은 이 진입 조건 안에서 읽어야 합니다. 전체 ingress 요청 수를 원하면 더 앞의 middleware·HTTP adapter 경계에서 완료 계측을 설계하고 중복 기록을 막습니다.

또한 Node의 응답 finish는 서버가 응답을 운영체제에 넘긴 시점이며 클라이언트 수신 완료를 뜻하지 않습니다. 중간 연결 종료는 finish가 없을 수 있으므로 별도 종료·중단 조건이 필요합니다. 이 코드의 duration은 인터셉터 진입 이후의 서버 구간으로, 앞선 middleware·Guard·네트워크까지 포함하는 사용자 전체 지연과 구분합니다.

사용자 ID나 query string을 포함한 raw URL을 label로 쓰면 시계열 cardinality가 빠르게 늘어납니다. 컨트롤러 prefix까지 구분해야 한다면 계측 계층에서 정규화한 route template을 조합합니다.

먼저 앞에서 만든 서비스와 컨트롤러를 MetricsModule에 묶습니다. AppModule에서 만드는 인터셉터도 같은 서비스를 받아야 하므로 MetricsService를 exports에 넣습니다.

import { Module } from '@nestjs/common';
import { MetricsController } from './metrics.controller';
import { MetricsService } from './metrics.service';

@Module({
  controllers: [MetricsController],
  providers: [MetricsService],
  exports: [MetricsService],
})
export class MetricsModule {}

서비스 등록은 MetricsModule 한곳에 두면 컨트롤러와 인터셉터가 같은 인스턴스의 Registry를 사용합니다. 아래 AppModule은 이 모듈을 가져오고 HttpMetricsInterceptor를 전역 인터셉터로 등록합니다.

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core'; // APP_INTERCEPTOR 임포트
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MetricsModule } from './metrics/metrics.module';
import { HttpMetricsInterceptor } from './metrics/http-metrics.interceptor';

@Module({
  imports: [MetricsModule], // MetricsModule 임포트
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_INTERCEPTOR, // 전역 인터셉터로 HttpMetricsInterceptor 등록
      useClass: HttpMetricsInterceptor,
    },
  ],
})
export class AppModule {}

• Prometheus: prometheus.yml 설정 파일에 NestJS 애플리케이션의 /metrics 엔드포인트를 스크랩하도록 타겟을 추가합니다.

  scrape_configs:
    - job_name: 'nestjs_app'
      static_configs:
        - targets: ['host.docker.internal:3000'] # Docker Desktop의 호스트 Nest 앱

  위 YAML은 prefix가 없는 /metrics route 기준입니다. 8장의 api prefix를 유지한다면 수집 job에 metrics_path: /api/metrics를 추가하거나 metrics route를 prefix에서 제외하는 설정을 선택해야 합니다. URI versioning도 사용하면 해당 실제 URL을 확인합니다. 앱이 정상인데 scrape가 404라면 먼저 수집 경로와 route 계약을 비교하세요.

  Prometheus와 NestJS를 같은 Docker 네트워크에서 실행한다면 host.docker.internal 대신 NestJS 서비스 이름과 포트를 사용합니다. 컨테이너 안의 localhost는 Prometheus 컨테이너 자신을 가리킵니다.

  Docker로 Prometheus 실행: docker run -p 9090:9090 -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

• Grafana: Prometheus를 데이터 소스로 추가하고, NestJS 애플리케이션의 메트릭을 시각화하는 대시보드를 생성합니다. http_request_duration_seconds_bucket, http_requests_total 등의 메트릭을 활용하여 응답 시간, 요청 수 등을 시각화할 수 있습니다. Docker로 Grafana 실행: docker run -p 3001:3000 grafana/grafana-oss (기본 로그인: admin/admin)

직접 판단하기 동일 label의 기록 하나만 놓고 판단합니다. 이 인터셉터에 진입한 요청이 250 ms 뒤 finish를 발생시켰습니다. 관측값은 몇 초이며, 위의 classic histogram에서 le="0.1", le="0.5", le="1", le="2", le="5", +Inf 중 어느 누적 bucket이 1씩 늘까요? Guard가 인터셉터 전에 거절한 별도 요청도 이 counter에 더해질까요?

프로파일링(Profiling)이란?

프로파일링은 애플리케이션의 코드 실행을 분석하여 특정 함수나 코드 블록이 CPU 시간, 메모리, I/O 등 리소스를 얼마나 사용하는지 상세하게 측정하는 과정입니다.

모니터링이 시스템의 "전반적인 건강 상태"를 확인한다면, 프로파일링은 병목 후보 함수, 호출 경로, 메모리 보유 객체를 증거로 좁히는 데 사용됩니다. 샘플링 결과가 항상 정확한 한 줄의 원인을 보장하는 것은 아닙니다.

• 병목 현상 식별: 느린 함수, 과도한 CPU 사용, 메모리 누수 등을 정확히 파악합니다.
• 최적화 대상 선정: 성능 개선 작업의 우선순위를 정하는 데 도움을 줍니다.
• 리소스 사용 패턴 이해: 애플리케이션이 런타임에 리소스를 어떻게 사용하는지 이해합니다.

• Node.js 내장 프로파일러: --inspect 플래그를 사용하여 Chrome DevTools 또는 VS Code에서 프로파일링할 수 있습니다.
• clinic.js: Node.js 애플리케이션의 성능 병목을 시각적으로 분석하는 도구(Flamegraphs, Doctor, Bubbleprof 등).
• APM 도구: Datadog, New Relic 등은 프로파일링 기능을 함께 제공하여 코드 레벨에서의 상세한 분석을 지원합니다.

프로파일링 도구는 모두 같은 목적을 갖지만, CPU 병목, 이벤트 루프 지연, 메모리 누수, 분산 트레이스 중 무엇을 좁힐지에 따라 선택 기준이 달라집니다.

Node.js 런타임 프로파일링

가장 간단하게 Node.js 애플리케이션을 프로파일링하는 방법입니다.

node --inspect dist/main # 또는 nest start --debug

콘솔에 Debugger listening on ws://127.0.0.1:9229/...와 같은 메시지가 출력됩니다.

Remote Target 섹션에 실행 중인 Node.js 인스턴스가 나타납니다.

inspect 링크를 클릭합니다.

Chrome의 공식 Node 프로파일링 안내는 전용 Node DevTools의 Performance 패널을 사용합니다. 웹페이지의 전체 로딩 프로파일과 Node의 CPU 프로파일을 구분하고, 같은 endpoint·부하·기록 시간을 두고 비교합니다.

• DevTools가 열리면 Performance 탭으로 이동합니다.
• 좌측 상단의 원형 Record 버튼을 클릭합니다.
• 이제 NestJS 애플리케이션에 트래픽을 발생시킵니다 (예: Postman으로 여러 번 요청 보내기, Jmeter로 부하 테스트).
• 충분한 트래픽이 발생한 후 Stop 버튼을 클릭합니다.

• 기록된 데이터가 로드되면 Flame Chart를 통해 함수 호출 스택과 각 함수의 실행 시간을 시각적으로 확인할 수 있습니다. 넓은 블록은 해당 함수가 많은 시간을 소비했음을 의미합니다.
• Bottom-Up 탭에서는 각 함수가 자체적으로(Self Time) 또는 자식 함수를 포함하여(Total Time) 얼마나 많은 시간을 소비했는지 표 형태로 볼 수 있습니다. 이를 통해 CPU 시간을 많이 소모하는 병목 함수를 식별할 수 있습니다.
• Call Tree 탭에서는 함수 호출 흐름을 트리 형태로 탐색할 수 있습니다.

clinic.js 활용

현재 Clinic.js 공식 저장소는 적극적으로 유지보수되지 않으며 Node 내부 변화 때문에 실행이나 결과의 정확성이 영향을 받을 수 있다고 안내합니다. 아래 명령은 기존 도구의 사용 흐름을 설명한 예시입니다. 사용 중인 Node 버전에서 호환성을 확인하지 않은 채 새 분석의 기본 도구로 적용하지 말고, 먼저 위의 Node·DevTools 경로로 재현 가능한 CPU 증거를 확보하세요. 원 명령의 존재를 현재 Node 24에서 실행 검증됐다는 의미로 읽지 않습니다.

clinic.js는 Node.js 애플리케이션의 성능 문제를 진단하고 시각화하는 데 특화된 도구입니다.

npm install -g clinic

clinic doctor는 CPU, 이벤트 루프 지연, 메모리, GC(Garbage Collection) 등 다양한 지표를 수집하여 일반적인 Node.js 성능 병목을 진단하고 보고서를 생성합니다.

clinic doctor -- node dist/main.js # NestJS 앱 실행 명령

clinic doctor가 실행되는 동안 애플리케이션에 부하를 발생시킵니다.

분석이 완료되면 HTML 보고서가 자동으로 열립니다.

이 보고서는 병목 현상을 시각적으로 보여주고 개선을 위한 제안을 제공합니다.

clinic flame은 CPU 사용량을 상세하게 분석하여 Flamegraph를 생성합니다.

이는 특정 함수가 CPU를 얼마나 많이 소모하는지 시각적으로 파악하는 데 매우 효과적입니다.

clinic flame -- node dist/main.js

clinic doctor와 마찬가지로 실행 중 애플리케이션에 부하를 준 후, 완료되면 Flamegraph가 포함된 HTML 보고서가 열립니다.

성능 개선은 알림, 원인 좁히기, 프로파일 캡처, 수정 배포, 재측정까지 하나의 운영 루프로 관리해야 재발을 줄일 수 있습니다.

성능 모니터링과 프로파일링은 애플리케이션의 건강 상태를 지속적으로 확인하고, 문제 발생 시 신속하게 원인을 찾아 해결하며, 잠재적인 성능 병목을 선제적으로 제거하는 데 필수적인 활동입니다.

NestJS와 Node.js 생태계의 도구를 개발 및 운영 단계에 맞게 도입하면 안정적인 애플리케이션 운영에 도움이 됩니다.

이것으로 9장 성능 최적화와 스케일링을 모두 마칩니다.

프로파일링, 캐시, 데이터베이스 최적화, 수평 확장, 모니터링 지표를 기준으로 병목을 찾고 변경 효과를 확인하는 흐름을 정리했습니다.