Skip to main content

Enabling Core Dumps for PHP-FPM

S
Written by Salvador Aguilar
Updated over 2 weeks ago

When your PHP-FPM workers start dying silently with segmentation faults, you’re left staring at a wall of logs that say nothing. To help us understand what might be happening inside the memory at the moment of impact, you need a Core Dump.

A core dump is a file containing the process's address space (memory) at the time it terminated unexpectedly. With this file our Engineering team will be able to drill down on the issue and provide a solution.

Here is how to configure your Linux stack to catch these files.

  1. The PHP-FPM Pool Configuration

    By default, PHP-FPM limits the size of core dumps to zero. You need to tell the specific pool that it’s allowed to write these files to disk.

    1. Open your pool configuration file (usually /etc/php/8.x/fpm/pool.d/www.conf).
      ​

    2. Find or add the rlimit_core directive:
      ​

      rlimit_core = unlimited

  2. Adjusting System Limits (ulimit)

    Even if PHP wants to dump core, the Operating System might stop it. You need to ensure the user running PHP-FPM (usually www-data or php-fpm) has permission to write large files.


    ​For Systemd Services (Modern Linux)
    ​

    Most modern distributions use Systemd. You’ll need to override the service file:
    ​

    1. Run systemctl edit php8.x-fpm.service.
      ​

    2. Add the following lines:
      ​

      [Service]
      LimitCORE=infinity

  3. Configuring the Kernel Pattern

    By default, Linux might try to pipe the core dump to a specialized tool or hide it in a temporary directory. You should define a predictable path and filename.

    Edit /etc/sysctl.conf and add:

    kernel.core_pattern = /tmp/core-%e.%p.%h.%t

    • %e: Executable filename

    • %p: PID of the process

    • %t: Time of dump
      ​

  4. Setting Permissions

    The directory where you save the dumps (in this case, /tmp) must be writable by the PHP-FPM user. If you choose a custom directory like /var/log/php-cores, ensure the permissions are set:

    mkdir -p /var/log/php-cores
    chown www-data:www-data /var/log/php-cores
    chmod 775 /var/log/php-cores

    ​

  5. How to test it

    Once you’ve restarted your PHP-FPM service, you can test if it's working by sending a SIGSEGV signal to a running worker:

    # Find a child PID
    ps aux | grep php-fpm

    # Force a crash
    kill -11 <PID>


    ​Check your /tmp (or your defined path). If you see a file starting with core-php-fpm, congratulations—you’ve successfully generated the file.

Submitting the core-dumps to Monarx

To figure out why things crashed (we call it a Root Cause Analysis, or RCA), our engineering team needs those core dumps.
​
​How to Send Them Over

A Few Quick Technical Tips

  • Compression: Core dumps can be large because they're sparse files. Please use gzip or zip to compress them first!
    ​

  • Big Files (>5MB): If the file is over 5MB, please don't attach it directly to an email. Instead, just send us a secure link to where you stored it (like S3, Dropbox, or whatever secure transfer service you prefer).
    ​

  • Don't Forget the Context: To help us triage this faster, please include the output of php -v and let us know your specific OS distribution and version.

What Happens Next?

Once we get the dumps, our Engineering team will do a deep dive with a backtrace analysis to pinpoint exactly what instruction or memory state caused the crash. After the investigation, we'll send you a summary of what we found and a clear plan (a deployment plan) for the fix or configuration change needed to get the module running smoothly again.

Did this answer your question?