All Boomi runtimes, whether it be a standalone basic runtime, or a runtime cluster or cloud node, runs on a JVM. For some issues, you may need to generate a JVM Heap dump for troubleshooting purposes. To generate a heap dump, you can use the "jmap" java utility as described at this link:
http://docs.oracle.com/javase/7/docs/technotes/tools/share/jmap.html
JMAP will be distributed with the JDK you have on the server already for the basic runtime, runtime cluster or cloud.
If you only have the JRE installed, then you will need to download and install a JDK as well. (Boomi doesn't need to be updated to use the JDK: you just need to have it and know the directory it is installed to in order to proceed.) For best results, ensure the JDK you install is the same release as the Java version Boomi uses.
On Linux, you should have access to use the Boomi user profile. If this is impossible, see the Workarounds section below.
To use jmap, you first need to determine the process id (PID) of the JVM in question. This JVM might be the local basic runtime, the node of a runtime cluster, or an individual forked execution.
The instructions below are divided by operating system, and further by normal or forked executions. All standalone basic runtimes and most runtime clusters will use the Normal instructions. Clouds, and any runtime cluster that has been configured to use forked executions, will use the Forked Execution instructions if you need to take a heap dump against a specific forked execution process.
On Windows, the PID will be a number obtained by looking at either the Windows Task Manager, or the Windows Services Manager, on the server that your local basic runtime is installed on. If you have a runtime cluster, look on the runtime cluster's head node.
Once you have the Windows Task Manager open, select the Services tab and then find the name of your basic runtime listed. (Hint - it is sometimes prefixed with the word "basic runtime", for example, basic runtime - Mybasic runtimeName.) You will then be be able to see the PID number under the "PID" column.
If you need a heap dump from a forked execution, go to the Processes tab of Task Manager and note the PID of an executable called 'javaw.exe'. However, note that there may be several of these - there will be one javaw.exe for each running forked execution. It can be difficult to determine which javaw.exe entry correlates to the specific execution you want to diagnose. Therefore, try to run the process you're testing in isolation, and do not launch any other processes while collecting the PID, so that only one forked execution is running. This removes all ambiguity.
On Linux, you'll find the PID by using the PS command. On a standalone basic runtime, issue it on the server the basic runtime is installed on. On a runtime cluster (or on a cloud, if you want to see the heap usage of the controller JVM rather than a specific execution), issue it on the server the head node is installed on. Use the following command:
ps -elf | grep java
It will return a lot of data, but we are only worried about the first line. The PID should be visible shortly after the owner name (usually the Boomi user). In the example below, the PID has been put in bold:
0 S boomi 6923 1 0 80 0 - 687815 - Oct31 ? 00:04:23
To find the PID in this situation, follow these steps:
1. Find the execution in Process Reporting.
2. Click the "Actions" gear icon, select View Extended Information, and note the Node it is running under, along with the Execution ID.
3. Navigate to that Node server, and issue the grep command against the Execution ID, as shown in the following example:
ps -elf | grep execution-example-value-replace-with-yours-YYYY.MM.DD
4. The PID will be visible in the results, shortly after the owner name (usually the Boomi user). In the example below, the PID has been put in bold:
0 S boomi 6923 1 0 80 0 - 687815 - Oct31 ? 00:04:23
Once you have the PID, you are ready to run JMAP. Use the appropriate instructions below for your operating system.
Open a command prompt, then navigate to the directory where the JDK is installed. JMAP should be present under the /bin subdirectory. Issue the following command, replacing the values in <brackets> with the appropriate values, and removing the <> brackets. You can name the file anything you like, so long as it has the .hprof extension; here we used heap.hprof as an example.
jmap -dump:format=b,file=<some directory that the boomi user has write permission to>/heap.hprof <pid>
On Linux, you should run the jmap command as the same user that the Boomi software runs under. There is a security check that doesn't allow other users to issue jmap; only the Boomi user will function. Note: You will not be able to run jmap on Linux as the root user. This is a common mistake.
Navigate to the directory where the JDK is installed. JMAP should be present under the /bin subdirectory. Issue the following command, replacing the values in <brackets> with the appropriate values, and removing the <> brackets. You can name the file anything you like, so long as it has the .hprof extension; here we used heap.hprof as an example.
jmap -dump:format=b,file=<some directory that the boomi user has write permission to>/heap.hprof <pid>
If you have problems running JMAP on Linux, there are a couple of alternative methods you can try.
JCMD is another utility that can be used to generate a heap dump. JCMD will often work in situations where persistent problems are found using JMAP. This command is documented here:
https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/tooldescr006.html
Just like JMAP, you'll need the PID of the JVM you want to dump, and you'll need a JDK installed in order to use it. In either Windows or Linux, issue the following command in the /<jdk install directory>/bin where JCMD is found:
jcmd <PID> GC.heap_dump filename=Myheapdump.hprof
You can now either analyze the heap dump, or if needed, attach this output to the Support case.