Create a Java heap dump for Wowza Streaming Engine

When you open a Support ticket for Wowza Streaming Engine™ media server software, the Support engineers at Wowza Media Systems™ may ask you to provide a Java heap dump file. This article describes how to get a dump of the Java heap on Wowza Streaming Engine.

Install Java JRE or JDK

To use this method, Wowza Streaming Engine must be running the full Java JRE or JDK, which includes the jcmd tool. By default, Wowza Streaming Engine installs with a custom version of the Java JRE. In order to run the jcmd command, you must first complete these steps.

Notes: Starting with Wowza Streaming Engine 4.8.28, we're including the jdk.jcmd Java module with the JRE that ships with the installer. This eliminates the need to complete the steps in this section. For more, see Wowza Streaming Engine support for Java.

1. Download and install the full version of the Java JRE or JDK.
2. Set your installation of Wowza Streaming Engine to point to the full Java JRE or JDK you just installed. See Manually install and troubleshoot Java on Wowza Streaming Engine.

Create a Java heap dump using jcmd

Notes:

• The commands in this section must be run by the same user that owns the Java process that's running Wowza Streaming Engine.
• The default location for Java heap dump files created with the jcmd tool is the Wowza Streaming Engine [install-dir]/bin directory. You can provide an absolute path in your commands if you want to save the heap dump in a different location.

1. Open a command prompt and run the following command to find the process ID of the Java process that's running Wowza Streaming Engine (com.wowza.wms.bootstrap.Bootstrap):

   jcmd

2. Then, execute the following command:
    

   jcmd [pid] GC.heap_dump [heap-output-path]/heapdump.hprof

   Where [pid] is the process ID of the process running Wowza Streaming Engine and [heap-output-path] is the path to a writable directory that should contain the heap dump.

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

This method can be used with Wowza Streaming Engine 4.5.0.01 and later.

Note:

• To get started with the Wowza Streaming Engine REST API, see articles in the Overview section.
• If the server is not responding, these instructions may not work. We recommend using the jcmd method to create the heap dump instead.

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

Use this method for Wowza Streaming Engine 4.4.1 and earlier.

1. Use JConsole/JMX to connect to the running Wowza Streaming Engine.
    
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

To use this method, Wowza Streaming Engine must be running the Java JDK, which 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 Wowza Streaming Engine.
    
3. Execute the following command:
    

   jmap -dump:format=b,file=c:\Temp\heapdump.hprof [pid]

   Where [pid] is the process ID of the process running Wowza Streaming Engine.

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.

<VMOption>-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=${com.wowza.wms.AppHome}/logs</VMOption>

<VMOption>-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath="${com.wowza.wms.AppHome}/logs"</VMOption>

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

More resources 

• Create a Java stack trace for Wowza Streaming Engine