DALL·E 2025-03-05 19.11.14 - A modern computer screen displaying a few essential Docker commands in a terminal. The setup has a dark-themed terminal window with crisp, clear text .png

Capturing Heap Dumps, Thread Dumps, and JFR Profiles in Docker

Goal

This page shows how to capture heap dumps, thread dumps, and Java Flight Recorder (JFR) profiles in a Docker-based Appsmith deployment. These diagnostic files allow you to analyze memory usage, identify performance bottlenecks, and debug Out-of-Memory (OOM) errors.

Overview

If your Appsmith instance running in Docker is experiencing frequent container restarts, high memory consumption, or performance degradation, capturing these files can provide valuable insights.

Key diagnostic files:

  • Heap Dump – Provides a snapshot of memory usage, including allocated objects and their references.
  • Thread Dump – Captures the state of all active threads, helping diagnose deadlocks and high CPU usage.
  • Java Flight Recorder (JFR) Profile – Records runtime performance metrics, aiding in identifying bottlenecks.

Collecting and analyzing these files can help diagnose memory leaks, excessive garbage collection, or inefficient thread usage, leading to a more stable deployment.

  1. Capturing a Thread Profile (JFR) in Docker

    This section explains how to capture a Java Flight Recorder (JFR) thread profile in a Docker-based Appsmith deployment. A JFR profile helps analyze thread activity, execution patterns, and potential bottlenecks, making it useful for debugging high CPU usage, unresponsive applications, or frequent OOM-related crashes.

    1. To identify the container where Appsmith is running, use:

      docker ps
    2. Enter the container shell using:

      docker exec -it <container_name_or_id> bash

      Replace <container_name_or_id> with the actual container name or ID from the previous step.

    3. Check if the required profiling scripts exist inside the container by running:

      ls -lrta
      

      You should see thread-profile-start.sh and thread-profile-stop.sh in the list.

    4. Start capturing the thread profile using:

      ./thread-profile-start.sh
      
    5. Stop the profiling after reproducing the issue using:

      ./thread-profile-stop.sh
      
    6. Locate the generated JFR file inside the container at:

      /appsmith-stacks/heap_dumps/ad-hoc/<container_name>/thread-profile/

      The file will be named in the format profile-<container_name>.jfr, for example:

      /appsmith-stacks/heap_dumps/ad-hoc/2024_08_14_09_28/thread-profile/profile-appsmith-dfb7df69-4mdwr.jfr
    7. Exit the container and copy the JFR file to your local system using:

      docker cp <container_name_or_id>:/appsmith-stacks/heap_dumps/ad-hoc/<container_name>/thread-profile/<profile-filename> destination_path/<intended_file_name>
      

      Replace <container_name_or_id>, <profile-filename>, and destination_path/<intended_file_name> accordingly.

    8. Once copied, share the JFR file with the support team for further debugging

     

  2. Capturing a Heap Dump in Docker

    Capturing a heap dump in Docker involves taking a snapshot of the application's memory, which helps diagnose issues like Out of Memory (OOM) errors and memory leaks. In a Docker-based Appsmith deployment, heap dumps provide insights into memory usage and can help debug performance issues or unexpected crashes.

    1. To identify the container where Appsmith is running, use:

      docker ps
    2. If a container is restarting frequently or you need to take logs from a specific one, access it using:

      docker exec -it <container_name_or_id> bash
    3. Inside the container, check if the required script is available:

      ls -lrta

      You should see the script:

      record-heap-dump.sh
    4. Execute the script to capture the heap dump:

      ./record-heap-dump.sh

      After execution, you should see an output similar to:

      Dumping heap to filename ...
      Heap dump file created [1285426410 bytes in 9.988 secs]
    5. Verify that the heap dump has been created inside the container at:

      /appsmith-stacks/heap_dumps/ad-hoc/<container_name>/heap-profile/<file_name>.log
    6. Copy the heap dump file from the container to your local system:

      docker cp <container_name_or_id>:/appsmith-stacks/heap_dumps/ad-hoc/<container_name>/heap-profile/<file_name>.log destination_path/<intended_file_name>
    7. Share the heap dump file with the support team for further analysis.
  3. Capturing Thread Dump on Demand

    Capturing a thread dump in Docker provides a snapshot of all active threads in the application, including their states, locks, and stack traces. This is useful for diagnosing high CPU usage, deadlocks, slow performance, or unresponsive applications. In a Docker-based Appsmith deployment, thread dumps help identify bottlenecks and concurrency issues by analyzing thread activity at a specific moment.

    To capture a thread dump, you need to access the container, execute the appropriate script, and copy the generated file for further analysis.

    1. To identify the container where Appsmith is running, use:

      docker ps
    2. If a container is restarting frequently or experiencing performance issues, access it using:

      docker exec -it <container_name_or_id> bash
    3. Inside the container, check if the required script is available:

      ls -lrta

      You should see the script:

      record-thread-dump.sh
    4. Execute the script to capture the thread dump:

      ./record-thread-dump.sh
    5. Verify that the thread dump has been created inside the container at:

      /appsmith-stacks/heap_dumps/ad-hoc/<container_name>/thread-profile/<file_name>
    6. Copy the thread dump file from the container to your local system:

      docker cp <container_name_or_id>:/appsmith-stacks/heap_dumps/ad-hoc/<container_name>/thread-profile/<file_name> destination_path/<intended_file_name>
    7. Share the thread dump file with the support team for further analysis.

Conclusion

Capturing thread profiles (JFR), heap dumps, and thread dumps in Docker helps diagnose Out of Memory (OOM) errors, high CPU usage, deadlocks, and performance issues in an Appsmith deployment. After collecting the necessary files, the next step is to analyze them using tools like Eclipse Memory Analyzer (MAT) for heap dumps and JDK Mission Control for JFR files.

If you need further assistance, share the collected logs with the Appsmith support team along with details of the issue. Our team can help analyze the data and provide recommendations to resolve the problem efficiently.