Alert on PHP-FPM Process Limit Reached events

Hey there, Darian Vance here. Let’s talk about something that used to be a real thorn in my side: PHP-FPM worker limits. I remember the bad old days of an application slowing to a crawl, and my first clue would be an angry email. I’d then have to SSH into a server and manually `grep` through logs to find the dreaded `pm.max_children` warning. It was a reactive, time-consuming process. After realizing I was wasting a couple of hours a week on this fire-fighting, I automated it. This simple setup has saved me countless headaches by turning a hidden server problem into a proactive Slack alert, and today I’m going to walk you through it.

This isn’t about fancy, expensive monitoring tools. It’s a pragmatic, effective script that you can set up in under 30 minutes to get immediate value.

Prerequisites

Before we dive in, make sure you have the following ready:

• Python 3 installed on your server.
• Read access to your PHP-FPM log file (the location can vary, but it’s often in a system log directory).
• A Slack Incoming Webhook URL to send notifications to. You can easily adapt this for Discord, Teams, or even email.
• A task scheduler like cron.

The Guide: From Log Line to Slack Alert

Step 1: The Python Monitoring Script

First, we need a script that can read the log file, identify the specific warning, and fire off an alert. I’ll skip the standard project setup steps like creating a directory or a Python virtual environment, as you likely have your own workflow for that. Let’s jump straight into the Python logic.

Create a file named `fpm_monitor.py` and add the following code. I’ll explain what each part does right below it.

import os
import re
import requests
import datetime

# --- Configuration (loaded from a config.env file) ---
PHP_FPM_LOG_PATH = os.getenv('PHP_FPM_LOG_PATH')
SLACK_WEBHOOK_URL = os.getenv('SLACK_WEBHOOK_URL')
STATE_FILE_PATH = os.getenv('STATE_FILE_PATH', 'fpm_last_checked.txt')

# The specific error message we're looking for
FPM_LIMIT_REGEX = re.compile(r'WARNING: \[pool \w+\] server reached pm.max_children')

def get_last_checked_timestamp():
    """Reads the timestamp from the state file to avoid re-processing logs."""
    try:
        with open(STATE_FILE_PATH, 'r') as f:
            return float(f.read().strip())
    except (IOError, ValueError):
        # If file doesn't exist or is empty, we'll check from the beginning.
        return 0.0

def update_last_checked_timestamp(timestamp):
    """Writes the current log file's modification timestamp to the state file."""
    try:
        with open(STATE_FILE_PATH, 'w') as f:
            f.write(str(timestamp))
    except IOError as e:
        print(f"Could not write to state file {STATE_FILE_PATH}: {e}")


def send_slack_alert(message):
    """Sends a formatted message to a Slack webhook."""
    if not SLACK_WEBHOOK_URL:
        print("SLACK_WEBHOOK_URL not set. Skipping notification.")
        return
    
    payload = {'text': f':warning: PHP-FPM Alert: {message}'}
    try:
        response = requests.post(SLACK_WEBHOOK_URL, json=payload, timeout=10)
        response.raise_for_status()
        print("Slack notification sent successfully.")
    except requests.exceptions.RequestException as e:
        print(f"Error sending Slack notification: {e}")

def check_fpm_logs():
    """Main function to parse logs and trigger alerts."""
    if not all([PHP_FPM_LOG_PATH, SLACK_WEBHOOK_URL]):
        print("Error: Ensure PHP_FPM_LOG_PATH and SLACK_WEBHOOK_URL are set in your config.env file.")
        return

    try:
        # Get the last time the log file was modified.
        log_mod_time = os.path.getmtime(PHP_FPM_LOG_PATH)
    except OSError:
        print(f"Error: Could not access log file at {PHP_FPM_LOG_PATH}. Check path and permissions.")
        return

    last_checked_time = get_last_checked_timestamp()

    # This is the key: only process the file if it has been updated since our last run.
    if log_mod_time <= last_checked_time:
        print("No new log entries to process.")
        return

    print(f"Checking {PHP_FPM_LOG_PATH} for new entries...")
    
    found_events = []
    try:
        with open(PHP_FPM_LOG_PATH, 'r') as log_file:
            for line in log_file:
                if FPM_LIMIT_REGEX.search(line):
                    found_events.append(line.strip())
    except IOError as e:
        print(f"Could not read log file: {e}")
        return

    if found_events:
        # To avoid spam, we send one consolidated alert.
        alert_message = (
            f"Detected {len(found_events)} 'pm.max_children' events since last check. "
            f"This suggests the server is overloaded. "
            f"Most recent event: `{found_events[-1]}`"
        )
        send_slack_alert(alert_message)
    else:
        print("No 'pm.max_children' events found in new entries.")

    # Important: update our state file so we don't re-alert on these same events.
    update_last_checked_timestamp(log_mod_time)

if __name__ == "__main__":
    # In a real setup, you'd use a library like python-dotenv to load config.env
    # For this to work, you'll need to run 'pip install python-dotenv requests'
    # and add a couple of lines here to load the file.
    check_fpm_logs()

The Logic Explained:

• Configuration: Instead of hardcoding paths or secrets, the script reads them from environment variables. This is a best practice.
• State Management: This is the most crucial part. The script creates a file (`fpm_last_checked.txt`) to store the timestamp of when it last checked the log. On the next run, it compares this stored time with the log file’s “last modified” time. If the log hasn’t changed, it exits immediately. This prevents it from re-reading the entire log file every time and sending duplicate alerts.
• Regex Matching: It uses a simple regular expression to find the exact warning message.
• Consolidated Alerting: If it finds 100 matching lines, it doesn’t send 100 Slack messages. It sends one summary alert, which is much more operator-friendly.

Step 2: Create Your Configuration

In the same directory as your script, create a file named `config.env`. This is where you’ll store your settings. Your script runner will need to load this file. Remember to replace the placeholder paths with your actual ones.

# Full path to the PHP-FPM log file
PHP_FPM_LOG_PATH='/path/to/your/www-error.log'

# Your Slack Incoming Webhook URL
SLACK_WEBHOOK_URL='https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'

# Path to store the state file. Make sure the script has write permissions here.
STATE_FILE_PATH='/path/to/your/script/fpm_last_checked.txt'

Pro Tip: In my production setups, I never run scripts as the root user. I create a dedicated service user (e.g., `monitor`) with very specific, limited permissions: read-only access to the log file and write access only to its own directory where it stores the state file. This minimizes any potential security risk.

Step 3: Schedule the Script with Cron

The final step is to automate the script’s execution. Cron is perfect for this. We want it to run frequently enough to catch issues quickly, but not so often that it adds unnecessary load.

To run the script every 5 minutes, you’d set up a cron job like this. You’ll need a library like `python-dotenv` for the script to read the `config.env` file automatically, or you’ll have to source it manually before the command.

*/5 * * * * cd /path/to/your/script/ && python3 fpm_monitor.py >/dev/null 2>&1

The `>/dev/null 2>&1` part is important. It prevents cron from emailing you the script’s output (like “No new log entries to process”) every single time it runs, ensuring you only get notified when there’s an actual problem via Slack.

Common Pitfalls (Where I Usually Mess Up)

• File Permissions: This is the #1 issue. The user running the cron job must have read permissions on the PHP-FPM log file and write permissions for the directory containing the state file. Double-check this first.
• Log Rotation: If your system uses `logrotate` to archive old logs, the script might error out when the file it’s watching suddenly disappears. A simple fix is to ensure your script can handle an `OSError` gracefully, which the provided code does. More advanced solutions involve using `logrotate`’s `postrotate` directives.
• Environment Variables Not Loaded: If you run the script via cron, it won’t have the same environment as your interactive shell. That’s why explicitly changing directory (`cd`) and using a library to load the `config.env` file is the most reliable approach.

Conclusion

And that’s it! You now have a lightweight, robust monitoring script that watches for a critical performance indicator and tells you about it before it becomes a crisis. You’ve moved from being reactive to proactive. The real beauty of this pattern is its adaptability. You can easily tweak the regex to watch for fatal PHP errors, database connection timeouts, or any other log-based event you care about.

Happy monitoring!

– Darian Vance

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions