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.

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


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 writes 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 the location of the heap dump by including the filename query parameter in the request. For example, to write the heap dump to C:\Temp, 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


This method is recommended for versions of Wowza Streaming Engine prior to 4.5.0.01.

  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


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 on Stack Overflow.

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

More resources



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