Terminus 기반 Health Check 방법 NestJS

이번 글에서는 Terminus를 활용하여 NestJS 애플리케이션에서 Health Check를 구현하는 방법에 대해 심층적으로 설명드리겠습니다. 상태 확인은 복잡한 백엔드 시스템에서 매우 중요한 요소로, 시스템의 가용성과 신뢰성을 평가하는 데 도움을 줍니다. 이 글을 통해 Terminus 통합을 통해 어떻게 상태 확인을 설정하고 활용할 수 있는지 살펴보도록 하겠습니다.

Terminus란 무엇인가?

Terminus는 NestJS의 Health Check 및 Graceful Shutdown을 위한 패키지입니다. 이 패키지는 웹 애플리케이션의 상태를 점검하는 데 필요한 다양한 지표들을 제공합니다. 상태 점검은 애플리케이션의 정상 혹은 비정상 상태를 추적할 수 있게 해주며, 이를 통해 서비스의 가용성을 모니터링할 수 있습니다. 예를 들어, 인프라의 서비스나 구성 요소(예: Kubernetes)는 상태 확인 엔드포인트를 주기적으로 호출하여 서비스의 건강 상태를 확인하게 됩니다.

상태 점검의 주요 목적은 서비스 중단을 미리 감지하고, 시스템의 신뢰성을 향상시키는 것입니다. 다양한 서비스와의 연동성을 확인할 수 있는 Terminus는 이러한 상태 점검을 효과적으로 수행할 수 있도록 돕습니다. 아래 표는 Terminus가 제공하는 주요 상태 표시기들의 목록입니다.

상태 표시기 이름	설명
HttpHealthIndicator	HTTP 서비스 상태 확인
TypeOrmHealthIndicator	TypeORM 데이터베이스 상태 확인
MongooseHealthIndicator	MongoDB 데이터베이스 상태 확인
SequelizeHealthIndicator	Sequelize 데이터베이스 상태 확인
DiskHealthIndicator	디스크 사용량 확인
MemoryHealthIndicator	메모리 사용량 확인
MicroserviceHealthIndicator	마이크로서비스 상태 확인

이제 Terminus를 NestJS 프로젝트에 추가하는 방법을 살펴보겠습니다.

NestJS에 Terminus 설정하기

Terminus를 NestJS 프로젝트에 설정하려면 몇 가지 단계를 거쳐야 합니다. 첫 번째로, @nestjs/terminus 패키지를 설치해야 합니다. 다음의 명령어를 사용하여 패키지를 설치할 수 있습니다.

bash
npm install –save @nestjs/terminus

설치 후, Health Check 기능을 수행할 헬스 모듈(HealthModule)을 생성합니다. 이 모듈에서는 TerminusModule을 imports 배열에 포함시켜야 합니다. 아래는 HealthModule을 설정하는 예시 코드입니다.

typescript
import { Module } from @nestjs/common;
import { TerminusModule } from @nestjs/terminus;

@Module({
imports: [TerminusModule]
})
export class HealthModule {}

이제 HELLO, 해봅시다! 헬스 체크 기능을 제공할 Controller를 생성하여 상태 확인을 구현할 준비가 되었습니다. NestJS CLI를 사용하면 매우 간편하게 컨트롤러를 생성할 수 있습니다.

아래 명령어로 HealthController를 생성할 수 있습니다.

bash
nest g controller health

이제 HealthController를 아래와 같이 설정해보겠습니다.

typescript
import { Controller, Get } from @nestjs/common;
import { HealthCheckService, HttpHealthIndicator, HealthCheck } 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-docs, https://docs.nestjs.com),
]);
}
}

위 코드에서 HttpHealthIndicator의 pingCheck 메서드를 사용하여 외부 URL에 대한 Ping을 수행합니다. 이 방식은 지정된 URL이 정상적으로 작동하고 있는지를 확인하는 기본적인 방법입니다. 특정 URL이 정상적인 반응(HTTP 200 상태 코드를 반환)으로 응답하면 GET 요청은 성공적인 헬스 체크를 위한 HTTP 응답을 생성합니다.

상태 확인이 성공적이면 JSON 형태로 결과를 반환합니다:

json
{
status: ok,
info: {
nestjs-docs: {
status: up
}
},
error: {},
details: {
nestjs-docs: {
status: up
}
}
}

이제 다양한 상태 확인 기능을 가진 Terminus 기반 헬스 체크를 설정할 수 있습니다.

다양한 상태 표시기 사용하기

Terminus의 큰 장점은 여러 상태 표시기를 통해 다양한 서비스의 상태를 확인할 수 있다는 것입니다. 이번 섹션에서는 TypeOrmHealthIndicator와 DiskHealthIndicator를 활용하여 헬스 체크를 확장하는 방법을 소개하겠습니다.

TypeOrmHealthIndicator는 데이터베이스 연결을 확인하기 위해 사용됩니다. 아래의 코드를 통해 이 상태 표시기를 이용하여 데이터베이스의 상태를 점검할 수 있습니다.

typescript
import { TypeOrmHealthIndicator } from @nestjs/terminus;

@Controller(health)
export class HealthController {
constructor(
private health: HealthCheckService,
private db: TypeOrmHealthIndicator,
) {}

@Get()
@HealthCheck()
check() {
return this.health.check([
() => this.db.pingCheck(database),
]);
}
}

위의 코드는 데이터베이스에서 pingCheck 요청을 수행하여 데이터베이스 연결이 정상인지 확인합니다. 이와 같은 방식으로 헬스 체크를 설정하면, 데이터베이스의 상태를 실시간으로 모니터링 할 수 있어 시스템의 안정성을 높이는 데 큰 도움이 됩니다.

또한 DiskHealthIndicator를 통해 디스크 사용량도 모니터링할 수 있습니다. 아래 예시는 디스크의 사용량이 50%를 넘지 않는지를 확인하는 코드입니다.

typescript
import { DiskHealthIndicator } from @nestjs/terminus;

@Controller(health)
export class HealthController {
constructor(
private health: HealthCheckService,
private disk: DiskHealthIndicator,
) {}

@Get()
@HealthCheck()
check() {
return this.health.check([
() => this.disk.checkStorage(storage, { path: /, thresholdPercent: 0.5 }),
]);
}
}

이 코드에서는 루트(/) 경로의 디스크 사용량이 전체 용량의 50%를 초과할 경우 비정상으로 간주합니다. 이를 통해 애플리케이션이 디스크 공간 부족으로 인해 문제가 발생하기 이전에 조치를 취할 수 있도록 합니다.

아래 표는 각각의 상태 표시기와 그 사용 예제의 요약을 보여줍니다.

상태 표시기	설명	사용 예
TypeOrmHealthIndicator	데이터베이스 연결 체크	`this.db.pingCheck(database)`
DiskHealthIndicator	디스크 사용량 체크	`this.disk.checkStorage(storage, { path: /, thresholdPercent: 0.5 })`

이처럼 다양한 상태 표시기를 통해 애플리케이션의 헬스 체크를 확장할 수 있습니다.

결론

이번 포스트에서는 NestJS에서 Terminus를 활용한 Health Check 방법에 대해 다루었습니다. Terminus는 여러 상태 표시기를 통해 웹 애플리케이션의 정상 여부를 간편하게 검증할 수 있도록 돕습니다. 다양한 방법으로 상태 체크를 구현함으로써, 시스템의 신뢰성을 높이고 잠재적인 문제를 조기에 감지하여 대응할 수 있게 됩니다.

운영 환경에서의 경험과 도구의 필요성을 계속해서 탐구하시길 바랍니다. Terminus는 여러분의 애플리케이션 모니터링에 큰 도움이 될 것이며, 여러분의 서버가 항상 up 상태를 유지하도록 돕습니다. 다음에도 여러분께 유익한 내용을 전달할 수 있도록 하겠습니다!

자주 묻는 질문과 답변

질문1: Terminus를 사용하면 어떤 종류의 상태 체크를 할 수 있나요?
답변1: Terminus는 HTTP, 데이터베이스, 디스크, 메모리 등 다양한 서비스의 상태를 체크할 수 있습니다.

질문2: 헬스 체크 엔드포인트를 어떻게 구성하나요?
답변2: 헬스 체크를 위한 엔드포인트는 @Controller와 HealthCheckService를 사용하여 쉽게 구성할 수 있습니다.

질문3: 상태 체크 실패 시 어떻게 대처하나요?
답변3: 상태 체크가 실패할 경우, 해당 서비스에 대한 알림을 설정하거나, 중간에 오류 로그를 기록하여 문제를 빨리 진단할 수 있습니다.

질문4: Terminus는 NestJS 외에 다른 프레임워크에서도 사용할 수 있나요?
답변4: Terminus는 NestJS에 특화된 패키지이므로, 주로 NestJS 애플리케이션에서 활용됩니다.

Terminus 기반의 NestJS Health Check 방법 완벽 가이드!

Terminus란 무엇인가?

NestJS에 Terminus 설정하기

다양한 상태 표시기 사용하기

결론

자주 묻는 질문과 답변

관련 글