1---
2title: Implement Health Checks for Microservices
3impact: MEDIUM-HIGH
4impactDescription: Health checks enable orchestrators to manage service lifecycle
5tags: microservices, health-checks, terminus, kubernetes
6---
7 
8## Implement Health Checks for Microservices
9 
10Implement liveness and readiness probes using `@nestjs/terminus`. Liveness checks determine if the service should be restarted. Readiness checks determine if the service can accept traffic. Proper health checks enable Kubernetes and load balancers to route traffic correctly.
11 
12**Incorrect (simple ping that doesn't check dependencies):**
13 
14```typescript
15// Simple ping that doesn't check dependencies
16@Controller('health')
17export class HealthController {
18  @Get()
19  check(): string {
20    return 'OK'; // Service might be unhealthy but returns OK
21  }
22}
23 
24// Health check that blocks on slow dependencies
25@Controller('health')
26export class HealthController {
27  @Get()
28  async check(): Promise<string> {
29    // If database is slow, health check times out
30    await this.userRepo.findOne({ where: { id: '1' } });
31    await this.redis.ping();
32    await this.externalApi.healthCheck();
33    return 'OK';
34  }
35}
36```
37 
38**Correct (use @nestjs/terminus for comprehensive health checks):**
39 
40```typescript
41// Use @nestjs/terminus for comprehensive health checks
42import {
43  HealthCheckService,
44  HttpHealthIndicator,
45  TypeOrmHealthIndicator,
46  HealthCheck,
47  DiskHealthIndicator,
48  MemoryHealthIndicator,
49} from '@nestjs/terminus';
50 
51@Controller('health')
52export class HealthController {
53  constructor(
54    private health: HealthCheckService,
55    private http: HttpHealthIndicator,
56    private db: TypeOrmHealthIndicator,
57    private disk: DiskHealthIndicator,
58    private memory: MemoryHealthIndicator,
59  ) {}
60 
61  // Liveness probe - is the service alive?
62  @Get('live')
63  @HealthCheck()
64  liveness() {
65    return this.health.check([
66      // Basic checks only
67      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024), // 200MB
68    ]);
69  }
70 
71  // Readiness probe - can the service handle traffic?
72  @Get('ready')
73  @HealthCheck()
74  readiness() {
75    return this.health.check([
76      () => this.db.pingCheck('database'),
77      () =>
78        this.http.pingCheck('redis', 'http://redis:6379', { timeout: 1000 }),
79      () =>
80        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
81    ]);
82  }
83 
84  // Deep health check for debugging
85  @Get('deep')
86  @HealthCheck()
87  deepCheck() {
88    return this.health.check([
89      () => this.db.pingCheck('database'),
90      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
91      () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
92      () =>
93        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
94      () =>
95        this.http.pingCheck('external-api', 'https://api.example.com/health'),
96    ]);
97  }
98}
99 
100// Custom indicator for business-specific health
101@Injectable()
102export class QueueHealthIndicator extends HealthIndicator {
103  constructor(private queueService: QueueService) {
104    super();
105  }
106 
107  async isHealthy(key: string): Promise<HealthIndicatorResult> {
108    const queueStats = await this.queueService.getStats();
109 
110    const isHealthy = queueStats.failedCount < 100;
111    const result = this.getStatus(key, isHealthy, {
112      waiting: queueStats.waitingCount,
113      active: queueStats.activeCount,
114      failed: queueStats.failedCount,
115    });
116 
117    if (!isHealthy) {
118      throw new HealthCheckError('Queue unhealthy', result);
119    }
120 
121    return result;
122  }
123}
124 
125// Redis health indicator
126@Injectable()
127export class RedisHealthIndicator extends HealthIndicator {
128  constructor(@InjectRedis() private redis: Redis) {
129    super();
130  }
131 
132  async isHealthy(key: string): Promise<HealthIndicatorResult> {
133    try {
134      const pong = await this.redis.ping();
135      return this.getStatus(key, pong === 'PONG');
136    } catch (error) {
137      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
138    }
139  }
140}
141 
142// Use custom indicators
143@Get('ready')
144@HealthCheck()
145readiness() {
146  return this.health.check([
147    () => this.db.pingCheck('database'),
148    () => this.redis.isHealthy('redis'),
149    () => this.queue.isHealthy('job-queue'),
150  ]);
151}
152 
153// Graceful shutdown handling
154@Injectable()
155export class GracefulShutdownService implements OnApplicationShutdown {
156  private isShuttingDown = false;
157 
158  isShutdown(): boolean {
159    return this.isShuttingDown;
160  }
161 
162  async onApplicationShutdown(signal: string): Promise<void> {
163    this.isShuttingDown = true;
164    console.log(`Shutting down on ${signal}`);
165 
166    // Wait for in-flight requests
167    await new Promise((resolve) => setTimeout(resolve, 5000));
168  }
169}
170 
171// Health check respects shutdown state
172@Get('ready')
173@HealthCheck()
174readiness() {
175  if (this.shutdownService.isShutdown()) {
176    throw new ServiceUnavailableException('Shutting down');
177  }
178 
179  return this.health.check([
180    () => this.db.pingCheck('database'),
181  ]);
182}
183```
184 
185### Kubernetes Configuration
186 
187```yaml
188# Kubernetes deployment with probes
189apiVersion: apps/v1
190kind: Deployment
191metadata:
192  name: api-service
193spec:
194  template:
195    spec:
196      containers:
197        - name: api
198          image: api-service:latest
199          ports:
200            - containerPort: 3000
201          livenessProbe:
202            httpGet:
203              path: /health/live
204              port: 3000
205            initialDelaySeconds: 30
206            periodSeconds: 10
207            timeoutSeconds: 5
208            failureThreshold: 3
209          readinessProbe:
210            httpGet:
211              path: /health/ready
212              port: 3000
213            initialDelaySeconds: 5
214            periodSeconds: 5
215            timeoutSeconds: 3
216            failureThreshold: 3
217          startupProbe:
218            httpGet:
219              path: /health/live
220              port: 3000
221            initialDelaySeconds: 0
222            periodSeconds: 5
223            failureThreshold: 30
224```
225 
226Reference: [NestJS Terminus](https://docs.nestjs.com/recipes/terminus)
227