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, ShiftLeft 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 ShiftLeft 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:
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.:
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:
Your command to start Ocular therefore looks like:
Manually Provisioning Your Servers
Ocular determines the amount of memory needed and presents this information when you create and load a CPG.
When this happens, you can cancel the loading of the current CPG using CTRL-c. Then, close ShiftLeft 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: