# pm2

The pm2 plugin reports every process the local PM2 daemon manages. Each process becomes its own service with its status, CPU, memory and restart count. Turn it on for hosts that run Node apps under PM2.

## Enable it

Add `pm2` to the `plugins` array.

```json
{
  "plugins": ["pm2"],
  "pm2": {
    "refreshInterval": 10000
  }
}
```

| Option | Default | What it does |
|---|---|---|
| `refreshInterval` | `5000` | Milliseconds between reports. |

The example config and the client README list a `processes` option. The plugin does not read it. It always reports every process in `pm2 list`.

Keep the `pm2` section in the config even if it is empty. The plugin reads `config.refreshInterval` without a null check, so a missing section throws when monitoring starts.

## What it reports

One payload per PM2 process, per interval. The unique id is `pm2-<name>-<n>`, where `n` counts instances of the same name, so a cluster-mode app with four instances reports as four services.

- `name`, `pm_id`, `pid`.
- `status`, PM2's own value: `online`, `stopping`, `stopped`, `launching`, `errored` or `one-launch-status`.
- `monit.cpu` in percent and `monit.memory` in bytes.
- `restarts` (same value as `restart_time`) and `unstable_restarts`.
- `pm_uptime`, `created_at`, `autorestart`, `watch`, `username`, `node_version`.

## When it alerts

| Condition | Severity |
|---|---|
| `status` is `errored` | error |
| `status` is anything else other than `online` | warning |

The reason reads `<name> is <status>`.

A new problem does not notify on the first bad report. The server holds it until a second consecutive report from the same process is still bad, then sends the alert. When the process reports `online` again, the server resolves the alert.

## On the dashboard

The card is titled with the process name and labelled `Node · PM2`.

| Reading | Source | Warn | Crit |
|---|---|---|---|
| CPU bar | `monit.cpu` | above 70% | above 85% |
| STATUS | `status`, upper-cased | see below | see below |
| MEM | `monit.memory` | none | none |
| RESTARTS | `restarts` | more than 5 | none |

The STATUS metric is green for `online`. The dashboard does not map PM2's other words, so `stopped` and `errored` both show grey on that metric. The card's own color follows the server's verdict, so an errored process still shows a red card. CPU pressure raises the card color for display only.

A process that has not reported for 300 seconds shows `OFFLINE`.

## Requirements

- The agent must run as the user that owns the PM2 daemon, so it can connect to that daemon.
- The `pm2` npm package, which the plugins package installs as a dependency.

The client README notes that the pm2 plugin does not work when the agent runs as a systemd service. 
## Gotchas

- If the plugin cannot connect to PM2 at startup, it throws during setup. Setup runs for all plugins in sequence, so the failure stops the whole agent from starting, not only pm2.
- The first report arrives one interval after startup. Unlike most plugins, pm2 does not send a report immediately.
- The RESTARTS count is PM2's lifetime counter for the process, so a long-lived process can sit above 5 and stay amber.