Monitor Java JVM Heap Dump triggers via Email

Hey there, Darian Vance here. As a Senior DevOps Engineer at TechResolve, I’ve seen my fair share of late-night production fires. One of the most common culprits? The dreaded `OutOfMemoryError` in our Java services. For a long time, my morning routine involved manually checking server logs for heap dump (`.hprof`) files. It was a tedious, reactive process. I finally got fed up with wasting that time and built a simple, automated monitor to email me the second a heap dump is created.

This little script has been a game-changer. It turns a reactive chore into a proactive alert, letting us jump on memory issues before they cascade. Today, I’m going to walk you through how to set it up. It’s quick, effective, and will save you a ton of headaches.

Prerequisites

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

• A Java application running with the -XX:+HeapDumpOnOutOfMemoryError flag. This is what actually generates the dump file we’re looking for.
• Python 3 installed on the server where the Java application runs.
• Access to an SMTP server for sending emails (like Gmail, SendGrid, or your company’s internal relay).
• Permissions to create files and run a scheduled task (cron job) on the server.

The Guide: Step-by-Step

Step 1: The Core Logic – What Are We Doing?

The concept is straightforward. We’re going to write a Python script that:

1. Scans a specific directory where your JVM drops its heap dump files.
2. Keeps a log of the dump files it has already seen and reported.
3. If it finds a new .hprof file, it sends an email alert.
4. Finally, it updates its log so it doesn’t send duplicate alerts for the same file.

We’ll schedule this script to run every 15 minutes or so using a cron job. Simple, but incredibly effective.

Step 2: The Environment Setup

Alright, let’s get our project structure ready. I’ll skip the standard `mkdir` and `virtualenv` setup commands since you likely have your own workflow for that. The important part is to have a directory containing two files: our Python script (which we’ll call `monitor_dumps.py`) and a configuration file named `config.env`.

You’ll also need to install one Python library to handle the configuration file. You can do this with pip: `pip install python-dotenv`.

Step 3: The Configuration File

Create a file named `config.env` in your project directory. This is where we’ll store our sensitive details so they aren’t hard-coded in the script.

# --- Email Configuration ---
SMTP_SERVER="smtp.example.com"
SMTP_PORT=587
SMTP_USER="your_email@example.com"
SMTP_PASSWORD="your_app_password"
EMAIL_SENDER="server-alerts@example.com"
EMAIL_RECIPIENT="your_team@example.com"

# --- Monitoring Configuration ---
# The directory where your Java app drops .hprof files
HEAP_DUMP_PATH="/path/to/your/java/app/logs"

# The file to track already processed dumps
STATE_FILE="processed_dumps.log"

Pro Tip: For services like Gmail, I strongly recommend using an “App Password” instead of your main account password. It’s more secure and avoids two-factor authentication issues in your script.

Step 4: The Python Script

Now for the main event. Create a file named `monitor_dumps.py` and paste the following code into it. I’ve added comments to explain what each part does.

import os
import smtplib
import socket
from email.mime.text import MIMEText
from datetime import datetime
from dotenv import load_dotenv

# Load environment variables from config.env
load_dotenv('config.env')

# --- Configuration ---
SMTP_SERVER = os.getenv("SMTP_SERVER")
SMTP_PORT = int(os.getenv("SMTP_PORT", 587))
SMTP_USER = os.getenv("SMTP_USER")
SMTP_PASSWORD = os.getenv("SMTP_PASSWORD")
EMAIL_SENDER = os.getenv("EMAIL_SENDER")
EMAIL_RECIPIENT = os.getenv("EMAIL_RECIPIENT")
HEAP_DUMP_PATH = os.getenv("HEAP_DUMP_PATH")
STATE_FILE = os.getenv("STATE_FILE")

def send_alert_email(file_path):
    """Formats and sends an email notification."""
    hostname = socket.gethostname()
    file_name = os.path.basename(file_path)
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    subject = f"Alert: JVM Heap Dump Detected on {hostname}"
    body = f"""
    Hello Team,

    A new JVM heap dump file has been generated, indicating a potential OutOfMemoryError.

    Server: {hostname}
    File: {file_name}
    Path: {file_path}
    Timestamp: {timestamp}

    Please investigate the application logs on this server for more details.

    - Your Friendly Monitoring Bot
    """

    msg = MIMEText(body)
    msg['Subject'] = subject
    msg['From'] = EMAIL_SENDER
    msg['To'] = EMAIL_RECIPIENT

    try:
        with smtplib.SMTP(SMTP_SERVER, SMTP_PORT) as server:
            server.starttls()
            server.login(SMTP_USER, SMTP_PASSWORD)
            server.sendmail(EMAIL_SENDER, [EMAIL_RECIPIENT], msg.as_string())
        print(f"Successfully sent alert for {file_name}")
    except Exception as e:
        print(f"Failed to send email: {e}")
        return False
    return True

def get_processed_dumps():
    """Reads the state file to get a set of already reported dumps."""
    if not os.path.exists(STATE_FILE):
        return set()
    with open(STATE_FILE, 'r') as f:
        return set(line.strip() for line in f)

def update_processed_dumps(file_name):
    """Adds a new dump file to the state file."""
    with open(STATE_FILE, 'a') as f:
        f.write(f"{file_name}\n")

def check_for_new_dumps():
    """Main function to scan for and report new heap dumps."""
    print("Starting heap dump check...")
    if not HEAP_DUMP_PATH or not os.path.isdir(HEAP_DUMP_PATH):
        print(f"Error: Heap dump path '{HEAP_DUMP_PATH}' is not valid.")
        return

    processed_files = get_processed_dumps()
    found_new_dump = False

    for filename in os.listdir(HEAP_DUMP_PATH):
        if filename.endswith(".hprof"):
            if filename not in processed_files:
                print(f"New heap dump found: {filename}")
                full_path = os.path.join(HEAP_DUMP_PATH, filename)
                if send_alert_email(full_path):
                    update_processed_dumps(filename)
                    found_new_dump = True

    if not found_new_dump:
        print("No new heap dumps found.")

if __name__ == "__main__":
    check_for_new_dumps()

Step 5: Scheduling the Script with Cron

The last step is to automate it. We’ll use a cron job to run our script at a regular interval. I find every 15 minutes is a good balance.

To edit your user’s cron jobs, you’ll need to open your crontab file. Add the following line, making sure to adjust the path to wherever you placed your script. The key is that the command needs to execute from the directory containing both `monitor_dumps.py` and `config.env`.

`*/15 * * * * cd /path/to/your/script/directory && python3 monitor_dumps.py`

This command changes into the script’s directory first, ensuring it can find the `config.env` file, and then executes it.

Pro Tip: Before setting up the cron job, run the script manually once (`python3 monitor_dumps.py`) to make sure your SMTP settings are correct and there are no permission errors. It’s much easier to debug that way.

Common Pitfalls (Where I Usually Mess Up)

Even a simple setup can have hiccups. Here are a few things to watch out for:

• File Permissions: The user running the cron job needs read access to the Java log directory and write access to the directory where the script and `STATE_FILE` live. This is the most common issue I run into.
• SMTP Firewalls: Corporate networks or cloud security groups often block outbound traffic on standard email ports. Make sure your server is allowed to connect to your SMTP server on the specified port.

–

• Relative Paths in Cron: Cron jobs run in a very minimal environment. That’s why we use the `cd` command in our cron line—it ensures all file paths (like for `config.env` and `processed_dumps.log`) are resolved correctly.

Conclusion

And that’s it! You now have a lightweight, reliable monitor that will give you a crucial heads-up on potential memory issues. In my production setups, this alert is often the first sign of trouble, allowing my team to start investigating before users even notice a problem. It’s a small investment of time that pays huge dividends in system stability and peace of mind.

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