API with NestJS #98. Health checks with Terminus and Amazon ECS


This entry is part 98 of 156 in the API with NestJS

In one of the previous parts of this series, we learned how to use the Elastic Container Service to deploy multiple instances of our application. With this architecture, we maintain the target group, where each target is a single instance of our application. Thanks to that, the load balancer can route a particular API request to one of the registered targets.

Before redirecting the traffic to a particular target, the load balancer must know if the target can handle it. To determine that, the load balancer periodically sends requests to all registered targets to test them. We call those tests health checks. Thanks to performing them, the load balancer redirects the traffic only to the healthy targets.

A common approach is to create a designated endpoint that responds with the status of the application. To create it, we can use the tool called Terminus that NestJS is equipped with.

Using Terminus

Let’s start by installing the Terminus library.

To introduce an endpoint using Terminus, we should create a new controller.


The decorator is optional. As we can see under the hood, it allows for integrating Terminus with Swagger.

The most important thing above is the method. The code we have so far gives us a straightforward health check.

Built-in health indicators

We can perform more advanced checks using the health indicators built into NestJS. With them, we can verify a particular aspect of our application.

A very good example is the . Under the hood, it performs a simple SQL query to verify that our database is up and running. Doing that also ensures we’ve established a connection successfully.

There is also the , and if you are using some other ORM than TypeORM.



The method responds with a few properties:

    • if all of our health indicators report success, it equals . Otherwise, it can be or an . If the status is not , the endpoint responds with 503 Service Unavailable instead of 200 OK.
    • has data about each healthy indicator
    • contains information about every unhealthy indicator
    • has data about every indicator

Terminus offers more health indicators than just those related to the database:

    • allows us to make an HTTP request and verify if it’s working as expected
    • verifies if the process does not exceed a specific memory limit
    • checks how much storage our application uses

Custom health indicators

The above list contains health indicators for various ORMs. However, in some parts of this series, we’ve worked with raw SQL without any ORM.

Fortunately, we can set up a custom health indicator. To do that, we need to extend the class.


The method generates the health indicator result that ends up in the , , and objects.

To include it, we must call our new method in the .


Setting the health check with AWS

We need to point the load balancer to our endpoint. We do that when setting up the load balancer while starting tasks in our Elastic Container Service cluster.

Above, when creating the target group for our cluster, we specify as the health check path. Thanks to that, the load balancer periodically sends requests to the endpoint to determine if a particular instance of our NestJS application is working as expected.

If our task takes a long time to start, the load balancer might mark it as unhealthy and shut it down. We can prevent that by setting up the health check grace period in the above form. This gives our tasks additional time to reach a healthy state.

Verifying if our tasks are running

In the previous part of this series, we learned how to manage logs with Amazon CloudWatch. We also created the that logs every endpoint requested in our API.

Let’s look at the logs to verify if the load balancer requests our endpoint.

It’s also worth looking at the “Health and metrics” tab on the page dedicated to the service running our tasks.

If no target is healthy, the load balancer cannot handle the incoming traffic. So if our application does not work, it’s one of the first things to check when debugging.

It’s also worth looking at the “Deployment and events” tab. If something goes wrong with our deployment, the issue will often be visible in the “events” table.


In this article, we learned what health checks are and how to design them. We also used them together with Amazon Elastic Container Service to verify if the instances of our NestJS application were running correctly. While doing so, we’ve learned more about debugging our NestJS app running with AWS and why we need to care about the health of our tasks running in the cluster.

There is still more to learn about running NestJS with AWS, so stay tuned!

Series Navigation<< API with NestJS #97. Introduction to managing logs with Amazon CloudWatchAPI with NestJS #99. Scaling the number of application instances with Amazon ECS >>
Notify of
Inline Feedbacks
View all comments