PM2 — Log Handling

Log handling is an essential key factor in process management. Even though you might not be interested in your logs if everything went smooth. Wait for your first downtime and app failures and you’ll find your fastest way to get proper information about the current application situation within your log files.

This post is part of an extensive series about the Node.js process manager PM2. There might be another interesting post about PM2 in the series overview below.

PM2 Series Overview

  1. How to Start Your App With Node.js V8 Arguments
  2. Use NPM to Start Your App (Coming soon)
  3. Start Node.js App With Increased Memory Limit From Command Line (Coming soon)
  4. Start Node.js App With Increased Memory Limit From JSON Configuration (Coming soon)
  5. Start Multiple Apps With A Single Process File (JSON/JS/YAML) (Coming soon)

Introduction

This article shows example snippets from the command line of each executed PM2 command. We’ll use the Future Studio homepage (called homepage) and maintenance (called maintenance) projects to illustrate the log functionality.

Show Real-Time Logs

You can display any logs by your applications in real-time. This might be overwhelming if you’ve many incoming requests, because the logs will append sequentially. To show real-time logs of each started applications, use PM2’s logs command:

pm2 logs  

This command will also output previous log information of each application separated by an empty line. You can reduce the amount of previous log entries by passing the --lines option to the logs command. This will reduce the number of previous log entries for the current run by the specified number.

$ pm2 logs --lines=2
[PM2] Tailing last 2 lines for [all] processes

PM2: 2015-10-08 15:24:34: Starting execution sequence in -fork mode- for app name:maintenance id:1  
PM2: 2015-10-08 15:24:34: App name:maintenance id:1 online

homepage-0 (out): 151008/152457.897, [response], http://0.0.0.0:3000: get /images/favicon.ico {} 200 (3ms)  
homepage-0 (out): 151008/152457.984, [response], http://0.0.0.0:3000: get /images/favicon.ico {} 304 (3ms)

maintenance-1 (out): 151008/152448.194, [response], http://0.0.0.0:2014: get /images/futurestudio-logo-transparent.png {} 304 (3ms)  
maintenance-1 (out): 151008/152448.702, [response], http://0.0.0.0:2014: get /images/favicon.ico {} 200 (5ms)  

As you can see, the previous entries are reduced to only two lines. Any further log entries get appended to the real-time screen while you’re watching. If there are any error logs available for your applications, you’ll see them within the log view as well.

Show App Specific Logs

Mostly, you’re just interested of logs from a given application. You can add the application name used within PM2 to reduce the shown log entries only to the given app.

pm2 logs homepage  

The command above will only display the log entries for the homepage project. We’ll reduce the output of previous logs to 5 lines.

$ pm2 logs homepage --lines=3
pm2 logs homepage --lines=5  
[PM2] Tailing last 3 lines for [homepage] process

homepage-0 (out): 151008/152456.582, [response], http://0.0.0.0:3000: get /images/futurestudio-logo-transparent.png {} 304 (4ms)  
homepage-0 (out): 151008/152457.181, [response], http://0.0.0.0:3000: get /images/books/retrofit.png {} 304 (7ms)  
homepage-0 (out): 151008/152457.897, [response], http://0.0.0.0:3000: get /images/favicon.ico {} 200 (3ms)  

You can also reduce the log entries to the error ones. Passing the --err option to the logs command will only print error logs.

Flush Log Entries

There are situations when you want to remove old log entries and get back a fresh state. The section title already indicates the command to delete all log entries with PM2:

pm2 flush  

This will delete all log entries from every managed process, also the PM2 process.

$ pm2 flush
[PM2] Flushing /Users/marcuspoehls/.pm2/pm2.log
[PM2] Flushing
[PM2] /Users/marcuspoehls/.pm2/logs/homepage-out-0.log
[PM2] /Users/marcuspoehls/.pm2/logs/homepage-error-0.log
[PM2] Flushing
[PM2] /Users/marcuspoehls/.pm2/logs/maintenance-out-1.log
[PM2] /Users/marcuspoehls/.pm2/logs/maintenance-error-1.log
[PM2] Logs flushed

Reload Logs

If you’re using logrotate or any other application to support you handling the log entries, you can reload the old entries from your PM2 logs.

pm2 reloadLogs  

Log Format Specifications

Of course you can adjust the real-time log entries to your needs by adjusting the date format and you can also save the output and error logs to the same file. Let’s start with the date format specification. Therefore, you need to add the --timestamp <format> to the logs command. The <format> is a string representing a timestamp format, like "YYYY-MM-DD HH:mm Z".

$ pm2 logs --timestamp="YYYY-MM-DD HH:mm:ss Z"
[PM2] Streaming realtime logs for [all] processes
2015-10-08 16:16:24 +02:00 homepage-0 151008/161624.499, [response], http://0.0.0.0:3000: get /images/futurestudio-logo-transparent.png {} 304 (2ms)  
2015-10-08 16:16:25 +02:00 homepage-0 151008/161625.153, [response], http://0.0.0.0:3000: get /images/books/retrofit.png {} 304 (4ms)  

New log entries will have the format of timestamp assigned. PM2 will save the date of creation for every log entry. Even though old entries aren’t formatted in the specified way, there are timestamps available for every entry.

Output and Error Logs in Same File

PM2 allows you to store the output and error log entries in the same file. You have two options to configure this feature for your PM2 processes: either the -l (--log) or the same values for -o (--output) and -e (--error) options.

pm2 start server.js -o="/path/to/file.log" -e="/path/to/file.log"  
# or
pm2 start server.js -l="/path/to/file.log"  

Be aware that writing output and error logs to the same file may increase your effort to search for error entries within the log file.

Merge Log Entries in Cluster Mode

Using the cluster mode of PM2 will start multiple worker processes of your app and each process will have its own log file for normal output and errors. You can merge all log entries to a single application log file by passing the --merge-logs option during the start command:

pm2 start server.js --instances 2 --merge-logs  

Logrotate

PM2 has a module system that allow to extend the default with custom functionality. And there’s a plugin for logrotate integration to PM2: pm2-logrotate. It’s worth a look.

Do you prefer the native integration of PM2 with logrotate? Execute the following command to write a logrotate configuration to /etc/logrotate.d/pm2-<username>:

sudo pm2 logrotate -u <username>  

What Comes Next

This article showed you how to show application logs in real-time using available PM2 commands. You’ve learned how to use multiple options to customize the log output, like adding timestamps, reduce the displayed lines of previous log entries to and of course, how to show only log entries from a given app process.

The next article will guide you through the setup of PM2’s auto-completion feature for the command line utility.

Did we miss any useful command when managing application logs with PM2? Leave a comment or reach out @futurestud_io.


Additional Resources

Explore the Library

Find interesting tutorials and solutions for your problems.

Miscellaneous