Recovering from Errors

At this point, you are now familiar with some of the basic steps involved in interacting with PM2. You’ve learned how to create new processes with the help of PM2’s start command. You’ve also discovered how you can subsequently manage running processes with the help of commands such as list, stop, restart, delete, and show. We’ve yet to discuss, however, much of the real value that PM2 brings to the table in regard to managing Node processes. We’ll begin that discussion by discovering how PM2 can assist Node applications in automatically recovering from fatal errors.

If we were to start this application without the help of PM2 by passing it directly to the node executable, we would quickly find ourselves out of luck the moment our first error was thrown. Node would simply print the error message to the console before dumping us back to the command prompt, as shown in Figure 3-4.

Such behavior won’t get us very far in a real usage scenario. Ideally, an application that has been released to a production environment should be thoroughly tested and devoid from such uncaught exceptions. However, in the event of such a crash, an application should at the very least be able to bring itself back online without requiring manual intervention. PM2 can help us accomplish this goal.

In Figure 3-5, we remove our existing process from PM2’s list via the delete command and create a new instance of the poorly written application shown in Listing 3-3. Afterward, we wait several seconds before requesting an up-to-date process list from PM2.

Notice anything interesting here? Based on the values within the status, restart, and uptime columns, we can see that our application has crashed three times already. Each time, PM2 has helpfully stepped in and restarted it for us. The most recent process has been running for a total of 2 seconds, which means we can expect another crash (and automatic restart) 2 seconds from now.

PM2’s ability to assist applications in recovering from fatal errors in a production environment, while useful, is just one of several useful features the utility provides. PM2 is also equally useful within development environments, as we’ll soon see.

Responding to File Changes

Imagine a scenario in which you’ve recently begun work on a new Node project. Let’s assume it’s a web API built with Express. Without the help of additional tools, you must manually restart the related Node process in order to see the effects of your ongoing work—a frustrating chore that quickly grows old. PM2 can assist you in this situation by automatically monitoring the file structure of your project. As changes are detected, PM2 can automatically restart your application for you, if you instruct it to do so.

Figure 3-6 demonstrates this process. In this example, we first remove our currently running instance of my-bad-app. Next, we create a new instance of the application that was shown in our original example (see Listing 3-2). This time, however, we pass an additional flag, --watch, which instructs PM2 to monitor our project for changes and to respond accordingly.

As changes are saved to this project’s files, subsequent calls to PM2’s list command will indicate how many times PM2 has restarted the application, as seen in a previous example.

Monitoring Local Resources

Figure 3-10 demonstrates the output that is generated when PM2’s monit command is called. Here we see a continuously updated view that allows us to track the amount of CPU processing power as well as the amount of RAM consumed by each process being managed by PM2.

Monitoring Remote Resources

The information provided by PM2’s monit command provides us with a quick and easy method for monitoring the health of its processes. This functionality is particularly helpful during development, when our primary focus is on the resources being consumed within our own environment. It’s less helpful, however, as an application moves into a remote, production environment that could easily consist of multiple servers, each running its own instance of PM2.

PM2 takes this into account by also providing a built-in JSON API that can be accessed over the Web on port 9615. Disabled by default, the process for enabling it is shown in Figure 3-11.

In this example, we enable PM2’s web-accessible JSON API by calling the utility’s web command. PM2 implements this functionality as part of a separate application that runs independently of PM2 itself. As a result, we can see that a new process, pm2-http-interface, is now under PM2’s control. Should we ever wish to disable PM2’s JSON API, we can do so by removing this process as we would any other, by passing its name (or ID) to the delete (or stop) commands.

JSON Application Declarations

The application configuration file shown here provides PM2 with instructions on how to launch each of the applications included within this project. In this example, PM2 is instructed to restart each application if changes are detected to either’s file structure, or if they begin to consume more than 60MB of memory. The file also provides PM2 with separate environment variables to be passed to each process.

As expected, PM2 has created two instances for us, one for each of the applications referenced within our configuration file. As in previous examples, we can monitor the output that is generated with the help of PM2’s logs command (see Figure 3-13).

Zero Downtime Deployments

After launching an application in cluster mode, PM2 will begin forwarding incoming requests in a round-robin fashion to each of the eight processes under its control—providing us with an enormous increase in performance. As an added benefit, having our application distributed across multiple processors also allows us to release updates without incurring any downtime, as we will see in a moment.

As these steps take place, a brief period of downtime will be introduced, during which incoming requests to the application will be rejected—unless special precautions are taken. Fortunately, launching applications with PM2 in cluster mode provides us with the tools we need to take those precautions.

Previous examples have demonstrated the use of PM2’s restart command, which immediately stops and starts a specified process. While this behavior is typically not a problem within nonproduction environments, issues begin to surface when we consider the impact it would have on any active requests that our application may be processing at the moment this command is issued. When stability is of the utmost importance, PM2’s gracefulReload command serves as a more appropriate alternative.

When called, gracefulReload first sends a shutdown message to each of the processes under its control, providing them with the opportunity to take any necessary precautions to ensure that any active connections are not disturbed. Only after a configurable period of time has passed (specified via the PM2_GRACEFUL_TIMEOUT environment variable) will PM2 then move forward with restarting the process.

In this example, after receiving the shutdown message, our application responds by calling the close() method on the HTTP server that was created for us by Express. This method instructs our server to stop accepting new connections, but allows those that have already been established to complete. Only after 10 seconds have passed (as specified via PM2_GRACEFUL_TIMEOUT) will PM2 restart the process, at which point any connections managed by this process should already have been completed.

Figure 3-16 demonstrates the process by which this application can be started and subsequently restarted through the use of the gracefulReload command. By doing so, we are able to release updates without interrupting our application’s users.