• How to create a Java heap dump

    Sometimes the Support Engineers at Wowza Media Systems™ need you to provide a Java heap dump file for troubleshooting purposes. This article describes the various methods available for getting a "dump" of the Java heap on your Wowza media server.

    Contents


    Create a Java heap dump using the Wowza Streaming Engine REST API
    Create a Java heap dump using JConsole
    Create a Java heap dump using jHat
    Create a Java heap dump automatically when an OutOfMemory error is thrown
    More resources

    Create a Java heap dump using the Wowza Streaming Engine REST API


    Note: Wowza Streaming Engine™ software version 4.5.0.01 or later is required to use this method.
    To create a heap dump, use the following request:
    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/{serverName}/actions/heapDump
    This will write the heap dump to [install-dir]/WowzaStreamingEngine_HeapDump_${epoch}.hprof. The ${epoch} variable is replaced with the current system epoch in milliseconds.

    You can change where the heap dump is written to by including the filename query parameter in the request. For example, to write the heap dump to C:\Temp, you would use the following request:
    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/{serverName}/actions/heapDump?filename="C:\Temp\WowzaStreamingEngine_HeapDump_${epoch}.hprof"

    Create a Java heap dump using JConsole


    Note: Wowza Streaming Engine™ software or Wowza Media Server™ software is required to use this method. If you're running Wowza Streaming Engine software version 4.5.0.01 (or later), we recommend the easier REST API method.
    1. Use JConsole/JMX to connect to the running Wowza media server.

    2. On the MBeans tab, in the com.sun.management/HotSpotDiagnostics object, select the Operation section.

    3. In dumpHeap parameters, enter the following information:
      p0: [heap-output-path]
      p1: true - do a garbage collection before dump heap
      For example:
      p0: c:/dump.dmp
      p1: true
    4. Click the dumpHeap button.

    Create a Java heap dump using jHat


    Note: Your Wowza media server must be running the Java JDK to use this method. The Java JDK includes the Java Heap Analysis Tool (jHat) tool.
    1. Open a command prompt and "change directory" to the bin folder of the JDK installation.

    2. Use operating system tools such as ps (ps -ef on Linux or the Task Manager on Windows) to find the process ID of the Java process that's running the Wowza server software.

    3. Execute the following command:
      jmap -dump:format=b,file=c:\Temp\mymemorydump.hprof [pid]
      Where [pid] is the process ID of the process running the Wowza server software.

    Create a Java heap dump automatically when an OutOfMemory error is thrown


    You can configure Java to create a heap dump whenever an "OutOfMemory" error occurs.

    Wowza Streaming Engine software


    Open the [install-dir]/conf/Tune.xml file in a text editor, and then uncomment the following line:
    <VMOption>-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath="${com.wowza.wms.AppHome}/logs"</VMOption>
    Save the file and then restart the Wowza media server for the changes to take affect.

    Wowza Media Server software


    Open the [install-dir]/bin/setenv.sh file (Linux) or [install-dir]/bin/setenv.bat file (Windows) in a text editor, and then add the following to the JAVA_OPTS:
    -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=[path-to-heapdump]
    Where [path-to-heapdump] is the path to where the heap dump file is stored (such as /opt).

    For more information about using this method, see Using HeapDumpOnOutOfMemoryError parameter for heap dump for JBoss.

    Note: To force a garbage collection cycle before creating a heap dump, run the following command:
    jcmd [pid] GC.run

    More resources


    How to create a Java stack trace

    Originally Published: 02-25-2010.
    Updated: For Wowza Streaming Engine 4.5.0.01 on 08-18-2016.

    If you're having problems or want to discuss this article, post in our forum.