PM2 Logrotate Master Guide

Complete Guide to PM2 Log Rotation: Installation, Configuration, and Management

Log management is crucial for production applications, and PM2's log files can quickly consume disk space if left unmanaged. This comprehensive guide covers everything you need to know about pm2-logrotate, from installation to optimization.

What is pm2-logrotate?

pm2-logrotate is an essential PM2 module that automatically rotates log files to prevent them from consuming all available disk space. It supports various features like setting maximum log size, compressing log files, and specifying the number of logs to retain.

Why Log Rotation Matters

The Problem

• PM2 continuously writes to log files (stdout and stderr)

• Log files can grow to gigabytes in size over time

• Large log files cause performance issues:

  • Increased disk I/O operations

  • Memory pressure on the system

  • Slower file system operations

  • Backup complications

The Solution

Automatic log rotation prevents these issues by:

• Limiting individual log file sizes

• Maintaining a manageable number of historical logs

• Compressing old logs to save space

• Scheduling regular cleanup operations

Installation

Prerequisites

• PM2 installed and running your applications

• Node.js and npm available on your system

• Appropriate permissions (root or sudo if PM2 runs as root)

Install pm2-logrotate Module

pm2 install pm2-logrotate

For root users:

sudo pm2 install pm2-logrotate

Configuration Options Explained

Here's the recommended production configuration with detailed explanations:

Basic Configuration

pm2 set pm2-logrotate:max_size 1G
pm2 set pm2-logrotate:retain 2
pm2 set pm2-logrotate:compress false
pm2 set pm2-logrotate:dateFormat 'YYYY-MM-DD_HH-mm-ss'
pm2 set pm2-logrotate:workerInterval 30
pm2 set pm2-logrotate:rotateInterval '0 0 * * *'
pm2 set pm2-logrotate:rotateModule true

Configuration Parameters Breakdown

max_size: 1G

• Purpose: Maximum size a log file can reach before rotation

• Options: Use K (kilobytes), M (megabytes), or G (gigabytes)

• Impact: Smaller values = more frequent rotations but smaller files

• Example: 10M, 500M, 2G

retain: 2

• Purpose: Number of rotated log files to keep

• Impact: Higher values preserve more history but consume more disk space

• Recommendation: Balance between historical data needs and storage constraints

• Example: With retain: 2, you'll have current log + 2 rotated files

compress: false

• Purpose: Whether to compress rotated log files using gzip

• Benefits: Saves significant disk space (typically 80-90% compression)

• Drawbacks: Uses CPU during compression process

• Use Case: Set to true for space-constrained servers, false for CPU-sensitive applications

dateFormat: 'YYYY-MM-DD_HH-mm-ss'

• Purpose: Timestamp format for rotated log filenames

• Result: Creates files like app-out.log-2025-10-10_15-30-45

• Benefits: Easy identification and chronological sorting

• Alternative formats: YYYY-MM-DD, YYYYMMDD, YYYY-MM-DD_HH-mm

workerInterval: 30

• Purpose: How often (in seconds) to check log file sizes

• Performance Impact: Lower values = more responsive but slightly higher CPU usage

• Recommendation: 30-60 seconds for most applications

• Range: 10 seconds (high-frequency apps) to 300 seconds (low-traffic apps)

rotateInterval: '0 0 * * *'

• Purpose: Cron-format schedule for forced rotation

• Format: second minute hour day month dayOfWeek

• Example: '0 0 * * *' = daily at midnight

• Common schedules:

  • '0 0 * * *' - Daily at midnight

  • '0 0 * * 0' - Weekly on Sunday

  • '0 2 * * *' - Daily at 2 AM

  • '30 1 * * *' - Daily at 1:30 AM

rotateModule: true

• Purpose: Also rotate PM2's own internal module logs

• Benefits: Prevents PM2 system logs from growing uncontrolled

• Recommendation: Always set to true in production

Complete Setup Script

One-Liner Installation and Configuration

pm2 install pm2-logrotate && \
pm2 set pm2-logrotate:max_size 1G && \
pm2 set pm2-logrotate:retain 2 && \
pm2 set pm2-logrotate:compress false && \
pm2 set pm2-logrotate:dateFormat 'YYYY-MM-DD_HH-mm-ss' && \
pm2 set pm2-logrotate:workerInterval 30 && \
pm2 set pm2-logrotate:rotateInterval '0 0 * * *' && \
pm2 set pm2-logrotate:rotateModule true && \
pm2 restart pm2-logrotate && \
pm2 save

For Root Users

sudo pm2 install pm2-logrotate && \
sudo pm2 set pm2-logrotate:max_size 1G && \
sudo pm2 set pm2-logrotate:retain 2 && \
sudo pm2 set pm2-logrotate:compress false && \
sudo pm2 set pm2-logrotate:dateFormat 'YYYY-MM-DD_HH-mm-ss' && \
sudo pm2 set pm2-logrotate:workerInterval 30 && \
sudo pm2 set pm2-logrotate:rotateInterval '0 0 * * *' && \
sudo pm2 set pm2-logrotate:rotateModule true && \
sudo pm2 restart pm2-logrotate && \
sudo pm2 save

Managing Configuration

View Current Configuration

pm2 conf pm2-logrotate

Edit Individual Settings

# Change max file size to 2GB
pm2 set pm2-logrotate:max_size 2G

# Keep 5 rotated files instead of 2
pm2 set pm2-logrotate:retain 5

# Enable compression
pm2 set pm2-logrotate:compress true

# Change rotation schedule to 2 AM daily
pm2 set pm2-logrotate:rotateInterval '0 2 * * *'

Apply Changes

After any configuration change, restart the module:

pm2 restart pm2-logrotate
pm2 save

File Management Operations

View Log Files

# List all PM2 processes and their log files
pm2 list

# View log file locations
ls -la ~/.pm2/logs/

# Check log file sizes
du -sh ~/.pm2/logs/*

Manual Log Operations

# Clear all current logs (not rotated ones)
pm2 flush

# Force log file rotation
pm2 reloadLogs

# View real-time logs
pm2 logs

# View logs for specific app
pm2 logs app-name

Clean Up Old Logs

# Remove all rotated log files (keep current logs)
find ~/.pm2/logs/ -name "*.log-*" -delete

# Remove logs older than 7 days
find ~/.pm2/logs/ -name "*.log-*" -mtime +7 -delete

# Remove compressed logs
find ~/.pm2/logs/ -name "*.gz" -delete

Module Management

Check Module Status

# List all PM2 modules
pm2 ls

# Get detailed info about logrotate module
pm2 describe pm2-logrotate

# Show module configuration
pm2 show pm2-logrotate

Stop and Start Module

# Stop logrotate module
pm2 stop pm2-logrotate

# Start logrotate module
pm2 start pm2-logrotate

# Restart logrotate module
pm2 restart pm2-logrotate

Remove Module

# Completely uninstall pm2-logrotate
pm2 uninstall pm2-logrotate

# Alternative method if above fails
pm2 stop pm2-logrotate
pm2 delete pm2-logrotate

Performance Impact Analysis

Resource Usage

• CPU Impact: Minimal during normal operation (~0.1% CPU)

• Memory Usage: Typically 5-15 MB RAM

• Disk I/O: Brief spikes during rotation events

• Network: No network usage

Performance Considerations for Different Server Specs

2-core, 4GB RAM Server (Recommended Settings)

pm2 set pm2-logrotate:max_size 1G        # Moderate file sizes
pm2 set pm2-logrotate:retain 2           # Limited retention
pm2 set pm2-logrotate:compress false     # Avoid CPU overhead
pm2 set pm2-logrotate:workerInterval 60  # Less frequent checks

4-core, 8GB+ RAM Server (Performance Settings)

pm2 set pm2-logrotate:max_size 2G        # Larger files allowed
pm2 set pm2-logrotate:retain 5           # More historical data
pm2 set pm2-logrotate:compress true      # CPU available for compression
pm2 set pm2-logrotate:workerInterval 30  # More responsive monitoring

High-Traffic Production (Optimized Settings)

pm2 set pm2-logrotate:max_size 500M      # Smaller files, frequent rotation
pm2 set pm2-logrotate:retain 10          # Extended history
pm2 set pm2-logrotate:compress true      # Space efficiency
pm2 set pm2-logrotate:workerInterval 15  # Rapid response to size limits

Troubleshooting

Common Issues and Solutions

Module Not Rotating Logs

1

Step: Check if module is running

Run:

pm2 ls
# Look for pm2-logrotate in the list

2

Step: Verify configuration

Run:

pm2 conf pm2-logrotate

3

Step: Restart the module

Run:

pm2 restart pm2-logrotate

High CPU Usage During Rotation

• Cause: Large log files being compressed or rotated

• Solution:

  • Reduce max_size setting

  • Disable compression (compress: false)

  • Increase workerInterval to reduce check frequency

Disk Space Still Growing

1. Check retain setting:

pm2 conf pm2-logrotate | grep retain

1. Verify old logs are being deleted:

ls -la ~/.pm2/logs/ | grep -E "\.(gz|log-)"

1. Manual cleanup if needed:

find ~/.pm2/logs/ -name "*.log-*" -mtime +7 -delete

Module Installation Fails

• Network Issues: Check internet connectivity and npm registry access

• Permission Issues: Ensure proper user permissions for PM2 directory

• Corrupted Installation: Try uninstalling and reinstalling:

pm2 uninstall pm2-logrotate
pm2 install pm2-logrotate

Log Rotation Not Working as Expected

1

Step: Check cron format

Use a cron expression validator:

• Use https://crontab.guru to verify your rotateInterval syntax

2

Step: Verify file permissions

Run:

ls -la ~/.pm2/logs/
# Ensure PM2 user has write access

3

Step: Check PM2 daemon status

Run:

pm2 status

Best Practices

Production Environment

• Monitor disk space regularly

• Set up alerts for disk usage > 80%

• Test configuration changes in staging first

• Keep retention period aligned with business requirements

• Schedule log rotation during low-traffic periods

Development Environment

pm2 set pm2-logrotate:max_size 100M     # Smaller files for dev
pm2 set pm2-logrotate:retain 1          # Minimal retention
pm2 set pm2-logrotate:compress false    # No compression needed

Staging Environment

pm2 set pm2-logrotate:max_size 500M     # Medium file sizes
pm2 set pm2-logrotate:retain 3          # Moderate retention
pm2 set pm2-logrotate:compress true     # Test compression behavior

Alternative Solutions

Native Logrotate (Linux Systems)

# Setup system logrotate for PM2
sudo pm2 logrotate -u username

This creates a configuration file at /etc/logrotate.d/pm2-username with system-level log rotation.

Manual Cron Jobs

# Add to crontab for daily log cleanup
0 1 * * * pm2 flush
0 2 * * * find ~/.pm2/logs/ -name "*.log-*" -mtime +7 -delete

External Log Management

For enterprise environments, consider:

• ELK Stack (Elasticsearch, Logstash, Kibana)

• Fluentd for log collection and forwarding

• Centralized logging services (AWS CloudWatch, Google Cloud Logging)

Monitoring and Maintenance

Regular Health Checks

#!/bin/bash

# pm2-logrotate-health-check.sh

echo "=== PM2 Logrotate Health Check ==="
echo "Module Status:"
pm2 list | grep pm2-logrotate

echo -e "\nConfiguration:"
pm2 conf pm2-logrotate

echo -e "\nDisk Usage:"
du -sh ~/.pm2/logs/

echo -e "\nLog File Count:"
ls -1 ~/.pm2/logs/ | wc -l

echo -e "\nLargest Log Files:"
ls -laSh ~/.pm2/logs/ | head -10

Automated Monitoring Script

#!/bin/bash

# Check if log directory size exceeds threshold
LOG_DIR="$HOME/.pm2/logs"
THRESHOLD_GB=5

CURRENT_SIZE=$(du -s "$LOG_DIR" | cut -f1)
CURRENT_SIZE_GB=$((CURRENT_SIZE / 1024 / 1024))

if [ $CURRENT_SIZE_GB -gt $THRESHOLD_GB ]; then
    echo "WARNING: PM2 logs directory size ($CURRENT_SIZE_GB GB) exceeds threshold ($THRESHOLD_GB GB)"
    # Add your notification logic here (email, Slack, etc.)
fi

Conclusion

pm2-logrotate is essential for production PM2 deployments. The configuration provided in this guide balances performance, storage efficiency, and operational needs. Regular monitoring and proper configuration ensure your applications maintain optimal performance while preserving necessary log data for debugging and compliance requirements.

Remember to:

• Test configuration changes in non-production environments first

• Monitor disk usage regularly

• Adjust settings based on your application's specific logging patterns

• Keep retention policies aligned with your business and compliance requirements

By following this guide, you'll have a robust log management system that prevents disk space issues while maintaining the log data you need for effective application monitoring and troubleshooting.