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.