The last two blog posts on PM2 covered the utility overview and guided you through the process management including start, restart, stop and delete processes of various types (Node.js, Ruby, Python, PHP, etc).

Once you have processes started with PM2, you want to get a comprehensive overview of currently running apps. This article got you covered and shows you how to print the list of processes managed by PM2. Furthermore, we use PM2 to show detailed information on specific processes.

PM2 Series Overview

List Processes

The previous article shows how to start app servers with PM2. To get an overview of the processes currently managed by PM2, you can print out a comprehensive list using the command line utility.

pm2 list  
# or
pm2 ls|l|status  

pm2 ls|l|status will print the same information als pm2 list and you can use whatever you prefer. The list of processes will look like this:

$ pm2 list
│ App name │ id │ mode │ pid   │ status │ restart │ uptime │ memory      │ watching │
-------------------------------------------------------------------------------------
│ homepage │ 0  │ fork │ 39535 │ online │ 0       │ 31m    │ 86.355 MB   │ disabled │

The output shows basic information about the running processes like app name and id, the mode (fork or cluster), status, uptime, memory footprint, etc. Most of the time, this basic information is sufficient to see if all servers run correctly or if there are any issues to solve.

If you need parsable output, you can use PM2’s jlist command to receive the process list in JSON format. There is also a prettylist command to have beautified printing of the process list in JSON format using the command line.

[ { pid: 39535,
    name: 'homepage',
    pm2_env:
     { name: 'homepage',
       … 
     }
} ]

The JSON format is useful when making process information accessible via HTTP endpoints or as webhooks on process changes.

Process Details

In situations like downtimes and server restart failures, it’s not enough to just print a basic process overview. In those situations, you’re in the need of further information about the process itself and the location of error and output logs. You can print out detail process information using the show or describe commands:

pm2 show <process-name|process-id>  
# or
pm2 describe <process-name|process-id>  

Both commands (show and describe) result in the same output. The detailed process information listing contains data like .pid file location, app root path, out log and error log file paths, starting mode, uptime, interpreter, number restarts, etc.

$ pm2 describe homepage
Describing process with id 0 - name homepage  
 -----------------------------------------------------------------------------
│ status            │ online                                                  │
│ name              │ homepage                                                │
│ id                │ 0                                                       │
│ path              │ /Users/marcuspoehls/Dev/FutureStudio/homepage/server    │
│ args              │                                                         │
│ exec cwd          │ /Users/marcuspoehls/Dev/FutureStudio/homepage           │
│ error log path    │ /Users/marcuspoehls/.pm2/logs/homepage-error-0.log      │
│ out log path      │ /Users/marcuspoehls/.pm2/logs/homepage-out-0.log        │
│ pid path          │ /Users/marcuspoehls/.pm2/pids/homepage-0.pid            │
│ mode              │ fork_mode                                               │
│ node v8 arguments │                                                         │
│ watch & reload    │ ✘                                                      │
│ interpreter       │ node                                                    │
│ restarts          │ 0                                                       │
│ unstable restarts │ 0                                                       │
│ uptime            │ 31m                                                     │
│ created at        │ 2015-09-21T11:06:52.342Z                                │
 -----------------------------------------------------------------------------

If you didn’t choose a speaking app name, one of the most interesting parts in the process information output is the path. The path you help you assign the PM2 process to the actual project.

However, the other interesting parts within the listing are the error and out log paths. You can customize both paths by passing option parameters to the pm2 start command. By default, PM2 saves all log files within the hidden .pm2 folder in the root of your systems user home directory. The name of the log files are the app name concatenated by -error-x.log and -out-x.log. We’ll extensively cover the log handling with PM2 in a later post within this series.

PM2 Process Details Within a Git Repository

When navigating into the project folder of one of the managed processes, PM2 will additionally show revision control metadata if the project folder is also a revision control directory. We use the Future Studio homepage for illustration purposes within this series and if we cd into the project folder, which is a git repository as well, we’ll see the revision control metadata output below the process information.

$ pm2 describe homepage
Describing process with id 0 - name homepage  
 -----------------------------------------------------------------------------
│ status            │ online                                                  │
│ name              │ homepage                                                │
│ id                │ 0                                                       │
│ path              │ /Users/marcuspoehls/Dev/FutureStudio/homepage/server    │
│ args              │                                                         │
│ exec cwd          │ /Users/marcuspoehls/Dev/FutureStudio/homepage           │
│ error log path    │ /Users/marcuspoehls/.pm2/logs/homepage-error-0.log      │
│ out log path      │ /Users/marcuspoehls/.pm2/logs/homepage-out-0.log        │
│ pid path          │ /Users/marcuspoehls/.pm2/pids/homepage-0.pid            │
│ mode              │ fork_mode                                               │
│ node v8 arguments │                                                         │
│ watch & reload    │ ✘                                                      │
│ interpreter       │ node                                                    │
│ restarts          │ 0                                                       │
│ unstable restarts │ 0                                                       │
│ uptime            │ 31m                                                     │
│ created at        │ 2015-09-21T11:06:52.342Z                                │
 -----------------------------------------------------------------------------

Revision control metadata  
 ------------------------------------------------------------------------
│ revision control │ git                                                 │
│ remote url       │ ssh://gitserver@futustudio.io/urlto/homepage.git    │
│ repository root  │ /Users/marcuspoehls/Dev/FutureStudio/homepage       │
│ last update      │ 2015-09-21T11:37:51.000Z                            │
│ revision         │ ab555c55d555e55555555fg55h555ij555klm555            │
│ comment          │ latest commit message                               │
│ branch           │ develop                                             │
 ------------------------------------------------------------------------

The revision control metadata can be helpful in cases when the app doesn’t work properly and you’re wondering if you pulled the latest code changes from your co-workers.

What Comes Next

Within this and the previous two articles, you learned the fundamentals to manage your processes with PM2. The latest post guided you through the phases of starting, restarting, stopping and deleting servers. This posts shows you how to show an overview of currently managed processes by PM2 and how to output detailed information about an individual app instance.

The next post guides you through the update process of PM2 itself.

If you’ve additional tips and tricks to list or show detailed process information with PM2, please share them with us in the comments below or shoot us @futurestud_io.