pm2-syslog-sf

PM2 module to forward PM2 process events and logs to an external syslog server.

Description

This PM2 module automatically captures all PM2-managed process events and logs, forwarding them to your syslog server for centralized logging and monitoring. It listens to the PM2 event bus and forwards:

• Process lifecycle events (start, stop, restart, etc.)
• Application error logs (stderr output)
• Application standard logs (stdout output)

Installation

Install this module using PM2:

pm2 install pm2-syslog-sf

Or install a specific version:

pm2 install [email protected]

Features

• ✅ Automatic forwarding of all PM2 process events to syslog
• ✅ Captures both stdout and stderr from managed applications
• ✅ Structured log format with app name, process ID, and event details
• ✅ Can be disabled via environment variable
• ✅ Uses Unix domain socket for reliable local syslog delivery
• ✅ Minimal performance overhead

Configuration

Syslog Server

By default, logs are sent to the Unix socket address rsyslog. The module uses:

• Tag: pm2
• Facility: syslog (facility code 5)
• Address: rsyslog (Unix domain socket)

Environment Variables

SKIP_LOCAL_SYSLOG

Set this environment variable to disable the module:

export SKIP_LOCAL_SYSLOG=true
pm2 restart pm2-syslog-sf

When enabled, the module will stop itself and not forward any logs.

Log Format

Process Events

Process lifecycle events (start, stop, restart, etc.) are logged with WARNING level:

app=pm2 target_app=<app_name> target_id=<pm_id> restart_count=<count> status=<event>

Error Logs (stderr)

Application errors are logged with ERROR level:

app=<app_name> id=<pm_id> line=<log_content>

Standard Logs (stdout)

Application standard output is logged with NOTICE level:

app=<app_name> id=<pm_id> line=<log_content>

Requirements

• PM2: >=6.0.0 (uses PM2 6.0.13 with security fixes)
• Node.js: >=16.0.0
• Syslog Server: Must have a Unix socket at address rsyslog

Uninstallation

To remove the module:

pm2 uninstall pm2-syslog-sf

How It Works

1. The module connects to PM2's internal event bus using pm2.launchBus()
2. It listens for three types of events:
   • process:event - Process state changes
   • log:err - Error output from processes
   • log:out - Standard output from processes
3. Events are formatted and sent to syslog via the ain2 library
4. Syslog server handles persistence, rotation, and forwarding

Dependencies

• ain2 (^3.0.0) - Syslog client library
• pm2 (^6.0.13) - Process manager

Security

This version includes important security updates:

• PM2 upgraded from 4.5.6 to 6.0.13 (fixes multiple CVEs)
• Regular dependency updates for security patches

License

MIT

Repository

https://github.com/Silverfort/pm2-syslog-sf

Issues

Report issues at: https://github.com/Silverfort/pm2-syslog-sf/issues