Create a Memory Dump from HighByte Intelligence Hub

Introduction

A Java Virtual Machine (JVM) memory dump is also often referred to as a "crash dump" or "heap dump." This is an image of the JVM's memory that can be especially useful for troubleshooting application crashes. This is rarely critical for common operations but is an invaluable troubleshooting artifact for developers. In the event of a HigByte Intelligence Hub crash - especially when memory errors are involved - it may be necessary to generate a memory dump.

Developers will be able to inspect this memory dump file and use it to research the causes of errors at the time of the crash, and identify fixes or workarounds that may be necessary.

Capturing a Memory Dump on Crash

By default, a Java application may not completely stop after encountering a memory error, but it will rarely continue to work properly thereafter. Therefore, it is best to configure the application to 'crash' completely in the event of a memory error. And, for investigation purposes, it is best to dump memory as of that crash. The Java options -"XX:+HeapDumpOnOutOfMemoryError -XX:+CrashOnOutOfMemoryError" create that memory dump and crash the application respectively. These "JAVA_OPTS" lines are already in their respective start scripts near the top, but these options may need to be added. 

By default, memory dumps will be generated in the runtime directory - the same directory as the start script used to run Intelligence Hub. This will generate a memory dump with the file extension ".hprof" and a log file. 

Windows

In the start script runtime/start-windows.bat, the java options may be set as part of the JAVA_OPTS variable. 

set "JAVA_OPTS=-XX:+HeapDumpOnOutOfMemoryError -XX:+CrashOnOutOfMemoryError"

Linux

In the start script runtime/start-linux.sh, the java options may be set as part of the JAVA_OPTS variable. 

JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:+CrashOnOutOfMemoryError"

Dumping Memory Manually

It may be desirable at some point to manually generate a heap dump while Intelligence Hub is still running. This may be done with the following command - this command is a java command, and should be representative of both Windows and Linux-like operating systems:

jmap -dump:[live],format=b,file=<file-path> <pid>

In this command, '<file path>' should be set to represent where the memory dump will be saved, and '<pid>' must be set as the PID of the java platform running Intelligence Hub. This PID may be acquired from 'tasklist' on Windows, or 'ps' on Linux. 

Additional Considerations in Generating Memory Dumps

There are a few additional factors to consider when creating or planning to create memory dumps.

Ensure Available Disk Space

Disk space is important - the host must have enough disk space to write out the entirety of the memory dump, which could be quite large depending on how much memory the JVM is using.

Industrial data can generate large payloads, and frequently. Intelligence Hub itself can run on minimal hardware, but hardware can be a limiting factor, especially in memory. It is possible to overwhelm the Intelligence Hub with data on minimalistic installations. Providing more physical resources and allocating more memory to the JVM heap may solve or ease memory errors.

Because modern deployments generally have larger memory allocations, memory dumps may be expected to exceed four to eight gigabytes. In addition to having the disk space available to capture these, some infrastructure considerations should be given to how they will be shared - either to HighByte for support, or other internal consumers. These files will very likely be too big to email. Many office suites have solutions to host files for download (Google Drive, Microsoft OneDrive) and other dedicated hosting platforms such as DropBox. 

Clean Up Old Memory Dumps

Lastly, if a memory dump is created as a result of a crash, it may have happened more than once, and there may be several memory dumps generated. The largest of these dumps probably contains the most information related to how the memory heap was built up, which makes it the best candidate for investigation.

Once these memory dumps have been shared, they may be deleted. HighByte Intelligence Hub does not use these files after they have been created. 

Related Information

• Adjust Default JVM Heap Memory Size (Knowledge Base)