Skip to main content

Memory Size Recommendations

Ocular provisions a proportion of system memory, depending on the operating system. For example, the default provision for Linux is 25% (e.g., if the machine has 16 gigabytes of RAM, then the default provision is 4 gigabytes).

Disk overflow is enabled for Code Property Graphs (CPGs). Disk overflow moves cache entries to disk only when the number of entries in memory exceed the maximum memory allocation. Based on the query, Qwiet Ocular identifies the parts of the CPG needed, which are loaded into RAM. All other sections of the CPG are temporarily stored to disk.

However, when analyzing large applications, disk overflow can slow down performance. Instead, you can optimize Qwiet Ocular performance through the appropriate combination of memory and disk sizes, either by automating the provision of your servers or by doing it manually.

Note that estimating the necessary amount of memory is non-trivial.

Automating the Provision of Your Servers​

Before using Ocular to examine a specific application or application version, use the following script to estimate the required memory size:

sl ocular -- --script scripts/memory-recommendation.sc --params artifactPath=<inputPath>

Be sure to replace <inputPath> with the path to your application.

In the last line of the output, Ocular returns the recommended heap size (in megabytes) that you need in order to run Ocular with that application, i.e.:

script finished successfully
3633

In the above example, Ocular estimates that you'll need a heap size of 3633 megabytes. We recommend that you use a heap size that includes an additional 20% to ensure that you have sufficient physical memory on your server for other requirements (e.g., Java). Therefore, you would want to use a heap size of approximately 4000 megabytes for this example.

Each time you start Ocular, you can append the following to the start command to ensure the proper memory allocation: -J-Xmx<heapsize>.

Your command to start Ocular therefore looks like:

sl ocular -- -J-Xmx4000m

Manually Provisioning Your Servers​

Ocular determines the amount of memory needed and presents this information when you create and load a CPG.

importCpg("yourApp.jar")
// ...
// debug output from java2cpg
// ...
The cpg.bin.zip you are loading is 63MB on disk and requires approximately 12712MB heap, but the current maximum heap size is 455MB. It is suggested that you provide a larger `-J-Xmx` setting, e.g. `-J-Xmx14g` to ensure that your machine has sufficient free physical memory available. Otherwise, disk overflow is automatically enabled, slowing performance.

When this happens, you can cancel the loading of the current CPG using CTRL-c. Then, close Qwiet using CTRL-c, and then restart it with more memory (sl ocular -- -J-Xmx14g).

If the available heap isn't sufficient, the you'll see output similar to the following to indicate that parts of the CPG are stored on disk, which slows Ocular's performance:

INFO heap usage (after GC) was 0.87 -> scheduled to clear 100000 references (asynchronously)
INFO attempting to clear 100000 references