NestJS 애플리케이션에 Health Check 추가하기: 단계별 가이드

NestJS 애플리케이션 내 Health Check 추가

NestJS 애플리케이션 내 Health Check 추가 방법을 소개하며, 상태 확인을 위한 구현 단계 및 관련 예제들을 다룹니다.

상태 확인의 필요성과 중요성

NestJS 애플리케이션 내 Health Check 추가는 애플리케이션을 모니터링하는 핵심 요소로 자리 잡고 있습니다. 상태 확인은 애플리케이션이 정상적으로 작동하는지를 판단하기 위한 중요한 메커니즘입니다. 사용자가 애플리케이션이 실행 중인지, 데이터베이스와의 연결이 정상인지, 서버 자원이 적절히 관리되고 있는지를 확인할 수 있는 방식이기 때문입니다. 이를 통해 문제를 조기에 감지하고 대응할 수 있는 기회를 제공합니다.

상태 확인의 기능

상태 확인 기능을 추가함으로써 특정 지표를 지속적으로 수집하고 모니터링할 수 있습니다. 예를 들어, 데이터베이스의 연결 상태, 디스크 사용량, 메모리 사용량 등을 확인하는 것이 가능합니다. 이러한 정보를 바탕으로 개발자와 운영자는 시스템의 상태를 평가하고, 필요 시 수정 및 보완 작업을 할 수 있습니다.

상태 체크 항목	설명	예시
데이터베이스 체크	데이터베이스 연결 및 상태 확인	DB 연결 성공 여부
디스크 상태 체크	디스크 용량 및 접근성 확인	사용 가능한 저장공간
메모리 상태 체크	애플리케이션 메모리 사용량 확인	메모리 사용 비율

소프트웨어와 하드웨어 오류

상태 확인은 단순히 현재 시스템의 상태를 파악하는 차원을 넘어, 실제 오류가 발생했을 경우 이를 신속하게 처리할 수 있도록 합니다. 예를 들어, 메트릭 수집 서비스는 시스템의 다양한 지표를 수집하여, 특정 조건이 충족될 경우 알림을 통해 운영자가 조치를 취할 수 있게 합니다. 따라서 하는 일이 비즈니스 로직과 무관하게도 애플리케이션이 정상 작동하는지 파악할 수 있어 신뢰성을 높이는 데 기여합니다.

시스템 모니터링의 장점

정기적인 상태 확인은 여러분의 NestJS 애플리케이션이 얼마나 건강하게 작동하고 있는지를 보여주는 중요한 지침이 됩니다. 이는 특히 배포 후 운영되는 시스템에서 필수적으로 여겨지며, 다운타임을 줄이고 사용자 경험을 향상시키는 데 큰 역할을 합니다. 오류 발생 시 신속한 대응이 가능하다는 점에서 실제 서비스 운영에 있어 큰 중요성을 지닙니다.

NestJS에서의 Health Check 구성 방법

이제 본론으로 들어가 NestJS 애플리케이션 내에서 Health Check를 추가하기 위한 구체적인 방법에 대해 알아보겠습니다. NestJS 프레임워크에서는 Terminus라는 강력한 라이브러리를 통해 Health Check 기능을 쉽게 통합할 수 있습니다. 이 라이브러리를 사용할 경우, 준비(Ready) 및 활성(Alive) 상태 확인을 간편하게 구현할 수 있습니다.

Terminus 모듈 설치

먼저, Terminus 패키지를 설치해야 합니다. 이를 위해 다음과 같은 명령어를 터미널에 입력하여 설치해 주세요:

bash
npm install @nestjs/terminus

설치가 완료되면, 여러분의 애플리케이션에서 해당 모듈을 사용할 수 있습니다. Terminus 모듈은 상태 체크 엔드포인트를 생성하고, 여러 가지 상태 확인 지표를 관리하는 역할을 합니다.

상태 체크 엔드포인트 설정

상태 체크를 위한 엔드포인트는 고객이 요청할 수 있는 API가 됩니다. 이 API는 애플리케이션의 상태를 확인할 수 있는 수단이 됩니다. 다음과 같은 코드 예제를 통해 HealthController를 생성할 수 있습니다.

typescript
import { Controller, Get } from @nestjs/common;
import { HealthCheck, HealthCheckService, HttpHealthIndicator, MicroserviceHealthIndicator } from @nestjs/terminus;

@Controller(health)
export class HealthController {
constructor(private health: HealthCheckService, private http: HttpHealthIndicator) {}

@Get()
@HealthCheck()
check() {
return this.health.check([
() => this.http.pingCheck(NestJS API, http://localhost:3000),
]);
}
}

여기서 @HealthCheck() 데코레이터는 서버가 요청을 받을 때 적절한 상태를 반환하게 하며, pingCheck 메소드를 사용하여 해당 URL로의 연결을 확인합니다.

통합되는 다른 지표

Terminus 모듈은 HTTP 체크 외에도 데이터베이스, 메모리, 디스크와 같은 다른 지표들도 지원합니다. 예를 들어, 데이터베이스 상태 확인을 위해 별도의 HealthIndicator를 추가할 수 있으며, 이를 통해 사용자 요구에 맞는 상태 확인 지표를 구성할 수 있습니다.

상태 체크 종류	설명
HttpHealthIndicator	HTTP 엔드포인트의 연결 상태
DiskHealthIndicator	디스크 사용량 체크
MemoryHealthIndicator	메모리 사용량 체크

이렇게 다양한 체크를 통합함으로써, 단 하나의 엔드포인트에서 여러 가지 시스템 지표를 확인할 수 있습니다. 이는 다양한 서비스에서 특정 문제 상황을 조기에 파악하고 빠르게 대응할 수 있도록 돕습니다.

실제 상태 확인 예제

이제 실제 데이터베이스와의 연결 상태를 확인해보는 예제를 구현해보겠습니다. Prisma ORM을 사용하는 경우, 다음과 같은 코드를 추가해 건강 상태를 점검할 수 있습니다.

Prisma ORM 설치

먼저, Prisma와 데이터베이스 클라이언트를 설치해야 합니다. 명령어는 다음과 같습니다.

bash
npm install @prisma/client

이후, PrismaService를 통해 데이터베이스의 상태를 점검할 수 있습니다. HealthController에 다음 메서드를 추가해 보겠습니다.

typescript
import { PrismaService } from ./prisma.service;

//…

@Get(database)
async checkDatabase() {
const health = await this.prismaService.$queryRawSELECT 1;
return { database: health!== null };
}

이 메서드는 데이터베이스에서 간단히 쿼리를 실행하여 응답을 제공함으로써, 데이터베이스가 제대로 연결되어 있는지를 확인합니다.

통합된 Health Check API

마지막으로, 모든 체크가 통합된 상태 확인 API를 끝내보겠습니다.

typescript
@Get()
@HealthCheck()
check() {
return this.health.check([
() => this.http.pingCheck(NestJS API, http://localhost:3000),
() => this.prismaService.$queryRawSELECT 1,
() => this.disk.checkStorage(storage, { thresholdPercent: 0.5, path: / }),
() => this.memory.checkHeap(heap memory, 300 * 1024 * 1024),
]);
}

여기서 보이는 것처럼, 다양한 상태 확인을 한 곳에 통합하여 사용자가 간편하게 자신의 NestJS 애플리케이션의 상태를 점검할 수 있도록 구현할 수 있습니다.

결론

결국, NestJS 애플리케이션 내 Health Check 추가는 애플리케이션의 안정성, 신뢰성, 가용성을 높이는 데 필수적인 요소입니다. 상태 확인 기능을 통해 실시간으로 애플리케이션의 상태를 파악할 수 있으며, 이는 신속한 문제 해결과 연관되어 있습니다.

여러분의 애플리케이션에 상태 확인 기능을 추가하여 보다 강력하고 효율적인 서비스를 제공해보세요. NestJS의 Terminus 라이브러리와 다양한 업데이트된 기능을 활용하여 항상 안정적인 서비스를 유지하도록 하세요.

자주 묻는 질문과 답변

1. NestJS에서 Health Check 기능은 어떻게 설정하나요?

NestJS 애플리케이션에 Health Check 기능은 Terminus 라이브러리를 사용하여 간편히 설정할 수 있습니다. 먼저, Terminus를 설치한 후, HealthController를 생성하여 다양한 체크를 구현하면 됩니다.

2. 상태 체크는 왜 필요한가요?

상태 체크를 통해 애플리케이션의 정상 작동 여부를 실시간으로 모니터링할 수 있습니다. 이는 소프트웨어나 하드웨어의 오류를 조기에 발견하고 대응할 수 있는 기회를 제공합니다.

3. 여러 체크를 통합할 수 있나요?

네, Terminus 라이브러리를 이용하면 HTTP 체크, 데이터베이스 상태 체크, 메모리 체크 등 다양한 체크를 하나의 API로 통합할 수 있습니다.

4. 어떤 프레임워크와 함께 사용하나요?

NestJS 프레임워크에서 Terminus 라이브러리를 사용하여 Health Check 기능을 추가합니다. 이는 Node.js 기반의 애플리케이션에서 유용하게 활용할 수 있습니다.

5. Prisma ORM과의 통합이 가능한가요?

네, Prisma ORM과 통합하여 데이터베이스의 상태도 점검할 수 있습니다. PrismaService를 통해 간단한 쿼리를 실행하여 데이터베이스 연결 상태를 확인할 수 있습니다.