# segi · PM2 monitoring · LLM integration guide

PM2 monitoring lets a host running PM2-managed Node processes report its
`pm2 jlist` snapshot to segi every minute. The dashboard renders running
processes, restart counts, CPU/mem, and flags instances that haven't reported
in >5 minutes.

## TL;DR

1. Create a project in segi, copy its `segi_pk_live_…` key.
2. Drop the agent script on the host. Run it under PM2 itself so it stays up.
3. Open Project → PM2 to see the snapshot.

## Ingest endpoint

- `POST https://segiapi.extn.ai/api/ingest/pm2`
- Header: `X-Segi-Project-Key: segi_pk_live_…`
- Body: the JSON output of `pm2 jlist` (an array of process objects).
- Same rate limit + allowed-domains rules as the event ingest path.

## Sample agent (from segi repo: `examples/pm2-agent/agent.js`)

```bash
SEGI_PROJECT_KEY=segi_pk_live_xxxxx \
SEGI_ENDPOINT=https://segiapi.extn.ai/api/ingest/pm2 \
SEGI_INSTANCE=web-01 \
node agent.js --loop
```

`--loop` polls every minute; without it the script does one-shot and exits.
The `SEGI_INSTANCE` env var is the stable identity for this host; reports for
the same instance replace each other (latest wins).

## Run the agent under PM2 itself

```bash
pm2 start examples/pm2-agent/agent.js --name segi-pm2-agent -- --loop
pm2 save
pm2 startup    # follow the printed command to enable boot-time start
```

## Dashboard semantics

- Each report replaces that instance's snapshot. Processes that disappear from
  a later report are removed from the dashboard.
- An instance with no report in >5 minutes shows a `stale` badge — it's still
  visible (so you know it existed) but greyed out.
- Click an instance to see per-process detail: CPU %, memory, restarts,
  uptime, current PM2 status (`online` / `errored` / `stopped`).

## Available on all plans

PM2 monitoring is not quota-gated — every plan tier includes it. The cost is
trivial because reports are small and replace-per-instance.

## Common errors

- `401 Invalid project key` — wrong / revoked / typo'd key.
- `403 Origin not allowed` — if the agent host's origin (Origin header isn't
  set by a Node fetch; this only fires from browser-driven reports).
- `400 expected array` — body wasn't `pm2 jlist` JSON.

## See also

- Sample agent source: `examples/pm2-agent/agent.js` in the segi repo.
- Run it from cron once a minute (remember to source nvm so the `pm2`
  binary is on PATH), or under PM2 itself as shown above.